# 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

Workflows in `.gitea/workflows/` check backend tests and wheel builds,
Playwright, lint, documentation, and a Compose image smoke test. They use
this repository's files and `.env.example`; no parent workspace is required.