app/development.md

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:

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, with the API under /api/v1. api.localhost reaches the same container, and 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, includes Redis, and needs no .env or proxy. See the facility guide. 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:

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:

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.

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 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