# Fluksio App

Connect a few nodes, give their messages names, and let Fluksio handle the
running. Use live flows for automation and batch runs for experiments, with
dashboards to see what happened.

This repository holds the FastAPI backend, flow engine and dashboard SPA.
The Docker image serves all three on one port.

## Layout

```text
backend/        FastAPI + SQLModel + Alembic + SQLite
  fluksio/flow/ the flow engine (nodes, pipeline, state backends, controller)
  fluksio/cli.py  `fluksio serve` / `enroll` / `worker`
worker/         the `fluksio-worker` distribution: the agent and the node runner
frontend/       React 19 + TanStack Router + Tailwind 4 + shadcn/ui
docs/           the public documentation site (zensical), served on docs.${DOMAIN}
compose.yml     the single container, as the getting-started guide runs it
docker/         the operator stack: compose.yml → compose.dev.yml → compose.local.yml (+ compose.traefik.yml)
scripts/        generate-client.sh, test.sh
```

## Install without Docker

Start an engine with Python 3.12 or newer on Linux or macOS:

```sh
pip install fluksio
fluksio serve
```

For the optional browser portal, sign up at [fluksio.com](https://fluksio.com)
and add an instance. Use the code it gives you:

```sh
fluksio enroll <code>
```

Your engine also works without enrollment. A machine that only runs nodes
for another engine needs just the worker package:

```sh
pip install fluksio-worker
FLUKSIO_WORKER_TOKEN='<worker-token>' fluksio-worker \
  --url wss://fluksio.example.com/api/v1/workers/attach --labels gpu
```

Replace the example address with your engine's URL and create a token as
described in [Remote workers](docs/code/workers.md).

## Getting started

Needs Docker with Compose v2, on x86-64 or arm64 such as a Raspberry Pi 4 or 5.

```sh
docker compose up -d           # http://localhost:8080
docker compose logs fluksio    # the admin password, printed once
```

Optional features (MQTT, InfluxDB, mail, …) are build-time extras; see `EXTRAS` in
`compose.yml`.

For development, with hot reload behind Traefik on port 80 (also needs `make` and `openssl`):

```sh
make init          # once: .env with generated secrets, `proxy` network, prints the admin login
make dev-local     # full stack at http://app.localhost
make down          # stop it
```

Without Docker:

```sh
make install       # uv sync + bun install
make dev-utils     # proxy and mailcatcher only
make dev-backend   # FastAPI on :8000, hot reload
make dev-frontend  # Vite on :5173
```

```sh
make test           # pytest + Playwright (the e2e half on its own stack, behind make dev's Traefik)
make lint           # ruff + mypy + biome
make generate-client  # regenerate the frontend SDK from the OpenAPI schema
```

`make help` lists every target. See [Development](development.md) for stack
options and checks.

## Documentation

The public site lives in [`docs/`](docs/) and is built with zensical:

```sh
make docs-serve   # live preview on :8000
make docs         # static build into ./site
```

It is served at `docs.${DOMAIN}` by the `docs` service in `docker/compose.yml`,
and `.gitea/workflows/docs.yml` builds it with `--strict` on every push.

## License

Copyright (C) 2026 Melvin Strobl - GNU Affero General Public License v3.0 or
later. See [LICENSE](LICENSE).