106 lines
3.2 KiB
Markdown
106 lines
3.2 KiB
Markdown
# 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).
|