166 lines
7.3 KiB
Markdown
166 lines
7.3 KiB
Markdown
# Development
|
|
|
|
Run all commands from this repository's root unless a step says otherwise.
|
|
|
|
## Run the app
|
|
|
|
### Docker development stack
|
|
|
|
Install Docker with Compose v2, Make and OpenSSL, then run:
|
|
|
|
```sh
|
|
make init # create .env, generate secrets and create the proxy network
|
|
make dev-local # start the app and docs behind the local proxy
|
|
make down # stop the stack
|
|
```
|
|
|
|
`make init` prints the admin login. The app image contains the engine, API and
|
|
built dashboard on port 8000. The proxy exposes it at
|
|
[app.localhost](http://app.localhost), with the API under `/api/v1`.
|
|
[api.localhost](http://api.localhost) reaches the same container, and
|
|
[docs.localhost](http://docs.localhost) serves the documentation.
|
|
|
|
Development targets default to `DOMAIN=localhost`, independently of `.env`.
|
|
Use `make dev-local DOMAIN=example.test` to choose another development domain.
|
|
`make dev-lan APP_PORT=8080` also publishes the app on the machine's LAN address
|
|
for devices that cannot resolve the proxy hostname.
|
|
|
|
`make dev` runs in the foreground with additional published ports:
|
|
|
|
| URL | Service |
|
|
|---|---|
|
|
| http://app.localhost, http://api.localhost | app through Traefik |
|
|
| http://localhost:8000 | dashboard and API directly |
|
|
| http://localhost:8090 | Traefik dashboard |
|
|
| http://localhost:1080 | captured mail; SMTP on port 1025 |
|
|
|
|
For `make dev-local`, read captured mail with
|
|
`docker logs -f fluksio-app-mailcatcher-1`. The proxy is the only published
|
|
port in that setup.
|
|
|
|
### Single-container setup
|
|
|
|
`docker compose up -d` uses the top-level `compose.yml`. It serves the app on
|
|
[localhost:8080](http://localhost:8080), includes Redis, and needs no `.env` or
|
|
proxy. See the [facility guide](docs/getting-started/facility-automation.md).
|
|
This setup has separate data from the development stack.
|
|
|
|
For the operator stack under `docker/`, use the Makefile targets. They pass
|
|
the project name and env-file path explicitly. Its files layer as
|
|
`compose.yml` → `compose.dev.yml` → `compose.local.yml`; CI uses
|
|
`compose.ci.yml` as its final overlay. `compose.traefik.yml` supplies a
|
|
separate production edge proxy.
|
|
|
|
### Without Docker
|
|
|
|
Install uv and Bun, then run `make install`. Use two terminals:
|
|
|
|
```sh
|
|
make dev-backend # FastAPI on :8000 with hot reload
|
|
make dev-frontend # Vite on :5173
|
|
```
|
|
|
|
The backend creates SQLite in `DATA_DIR` (`backend/flow-data` by default).
|
|
No database service is required. `make dev-utils` starts just the proxy and
|
|
mailcatcher if you need them. The Docker development API also accepts the
|
|
Vite origin, so a host Vite process can use it.
|
|
|
|
## Reloading changes
|
|
|
|
`docker/compose.dev.yml` mounts `backend/fluksio` and `worker/fluksio_worker`
|
|
into the API container. Uvicorn watches both, so changes restart the engine
|
|
and local workers. The adjacent `develop.watch` settings apply only to
|
|
`docker compose watch`; the Makefile's detached targets use the mounts.
|
|
|
|
The dashboard is built into the image. After a UI change, run:
|
|
|
|
```sh
|
|
make rebuild-frontend
|
|
```
|
|
|
|
This preserves the running stack's domain, overlays and LAN port.
|
|
|
|
## Development services
|
|
|
|
The development Compose file includes services for trying integrations:
|
|
|
|
- **Mosquitto:** anonymous MQTT at `mosquitto:1883` inside the stack.
|
|
- **InfluxDB:** `http://influxdb:8086`, organization and bucket `fluksio`,
|
|
development token `fluksio-dev-token`.
|
|
- **Mailcatcher:** captures outbound mail locally.
|
|
|
|
MQTT and InfluxDB have no published host ports. Redis persists flow state and
|
|
queued work. Without `REDIS_HOST`, a source-run engine uses memory instead.
|
|
Postgres and Adminer start only with the optional `analytics` profile.
|
|
|
|
## Configuration and secrets
|
|
|
|
`make init` copies `.env.example` to `.env` and generates initial secrets.
|
|
Edit `.env` directly and keep it out of git. After updating the repository,
|
|
compare it with `.env.example` for new settings. Generate additional secrets
|
|
with `openssl rand -hex 32`.
|
|
|
|
Backend settings load this repository's `.env` when run from `backend/`.
|
|
`FLUKSIO_ENV_FILE` selects another file, and exported variables override it.
|
|
The installed CLI uses the selected instance's data directory instead.
|
|
|
|
`DATA_DIR` holds the database, flow repository, credentials, artifacts and
|
|
managed node environment. Individual paths can be overridden. Docker stores
|
|
them under `/data`; see [Configuration](docs/reference/configuration.md).
|
|
|
|
## Tests
|
|
|
|
`make test` runs backend tests, frontend helper checks and Playwright tests.
|
|
|
|
- `make test-backend` runs pytest with coverage. Its temporary SQLite database
|
|
and test settings need no running services and leave development data alone.
|
|
The HTML coverage report is in `backend/htmlcov/`.
|
|
- `make test-checks` runs the frontend's `*.check.ts` helper scripts.
|
|
- `make test-frontend` starts an isolated `fluksio-test` stack behind the local
|
|
Traefik, then runs Playwright in a pinned container. Start `make dev-local`
|
|
or `make dev-lan` first. The test stack stays up for inspection at
|
|
`app.test.localhost`; `make down` stops it.
|
|
- `make test-webkit` runs the drag tests in WebKit against the same test stack.
|
|
|
|
Narrow a browser run with
|
|
`make test-frontend PLAYWRIGHT_ARGS="--grep flows"`.
|
|
The browser version comes from `frontend/package.json`. Container resolver
|
|
rules route `*.localhost` to Traefik, including in Chromium and WebKit.
|
|
|
|
Specs live in `frontend/tests/`. Authentication is saved once, then reused by
|
|
the desktop and mobile projects. The suite takes its origin from
|
|
`PLAYWRIGHT_BASE_URL`, and optionally `PLAYWRIGHT_API_URL`, independently of
|
|
`.env`. Its guard refuses public addresses because tests create and delete
|
|
flows, dashboards and users.
|
|
|
|
For manual visual checks, `frontend/scripts/capture-screenshots.mjs` captures
|
|
both themes at desktop and phone sizes. Set `APP_URL`, `FIRST_SUPERUSER` and
|
|
`FIRST_SUPERUSER_PASSWORD` in the environment, then run it from `frontend/`
|
|
with Bun in a Playwright-capable environment. `SCREENSHOT_DIR` selects the
|
|
output directory. `WEBSITE_URL` optionally adds screenshots of another site.
|
|
|
|
## Lint and documentation
|
|
|
|
`make lint` checks Python with Ruff and mypy, and the frontend with Biome.
|
|
`make format-frontend` applies frontend formatting. Install the repository's
|
|
commit hooks with `uv run --project backend prek install` after `make install`.
|
|
The backend hook also regenerates the frontend API client; run
|
|
`make generate-client` to request that explicitly.
|
|
|
|
Read [the design reference](DESIGN-GUIDELINES.md) before UI work.
|
|
`make docs` builds the documentation, and `make docs-serve` opens a preview.
|
|
|
|
## CI
|
|
|
|
Six workflows in `.gitea/workflows/`. They use this repository's files and
|
|
`.env.example`; no parent workspace is required.
|
|
|
|
| Workflow | Runs | Checks |
|
|
|---|---|---|
|
|
| `test-backend.yml` | push to `main`, pull requests | pytest on Python 3.12 and 3.14, and that both wheels build |
|
|
| `playwright.yml` | push to `main`, pull requests touching backend, frontend or Compose files | the Playwright suite in two shards, one Compose project each |
|
|
| `pre-commit.yml` | push to `main`, pull requests | the hooks above, plus strict mypy on the backend |
|
|
| `test-compose.yml` | push to `main`, pull requests touching backend, frontend or Compose files | that the production image comes up and serves the API and the dashboard |
|
|
| `docs.yml` | push to `main`, pull requests | that the documentation builds with `--strict` |
|
|
| `publish.yml` | a `v*` tag | that the tag matches both packages' versions, then publishes the worker and `fluksio` to PyPI |
|