Files

T

stroblme dea25ec08d One image for the whole app: engine, API and dashboard on one port

The backend image now builds the SPA and serves it on the API's own origin
(fluksio/spa.py), so an instance is a single container with no proxy, DNS,
port 80 or .env: `docker compose up -d` with the new compose.yml runs it on
localhost:8080. It starts on fluksio serve (persisted secret key, first
admin printed once) and brings its own Redis when REDIS_HOST is unset.

Slimmer: python:3.13-slim, no dev group, uv once, fastapi without the cloud
CLI. Optional features are per-feature extras (mqtt, influx, email, sentry,
ml, server for all) picked with the EXTRAS build argument; numpy moved to
`ml`. ffmpeg left the image for imageio-ffmpeg via the Modules screen.

The operator stack runs the same image with app. and api. routed to it; the
nginx frontend service, the LAN nginx proxy and DOMAIN in the backend are
gone, and the MCP issuer is FRONTEND_HOST.

2026-10-16 11:40:02 +02:00

5.4 KiB

Raw Blame History

Getting started: facility automation

Build a small temperature flow, then connect a real sensor when you're ready. No hardware required for the first lap.

Start Fluksio

You need Git and Docker with Compose v2. Clone the app repository and start its single container:

git clone https://git.stroblme.de/Fluksio/app.git fluksio
cd fluksio
docker compose up -d
docker compose logs fluksio

The first build takes a few minutes. The log shows the admin account and its password once, on the first start. Open http://localhost:8080 and sign in. Adding Python code requires that superuser account.

Everything runs in that one container on one port: the engine, its API and the dashboard. To use another port, change the left side of ports in compose.yml, for example "9000:8000". From another machine on your network, open http://<host-ip>:8080. Set FRONTEND_HOST in compose.yml to the address you open, since links for wall panels and mails are built from it.

The image starts minimal. MQTT, InfluxDB, outbound mail and the rest are extras. Add the ones you need to EXTRAS in compose.yml and rebuild:

      args:
        EXTRAS: "mqtt,influx"

docker compose up -d --build

Stop the container with docker compose down. Your data stays on the data volume for the next start.

Your first flow

Open Flows, create a flow named house, and use Add node to add an Inject node. In its panel:

Under Provides, add living_temperature with type float.
Under Settings, set the living_temperature value to 18.0 and Interval to 5 seconds.

This gives you a pretend sensor. Add a Function node with:

Consumes: living_temperature, type float.
Provides: heat_wanted, type bool.

In the code editor, enter:

def process(living_temperature):
    return {"heat_wanted": living_temperature < 21.0}

Message names connect the nodes automatically; there are no wires to draw. Save the code with ⌘S / Ctrl-S, then click Publish in the dock. Open Flow settings from the dock's pencil button and make sure Running is on.

Every five seconds, 18.0 should produce true. Select the Function and check the value under its heat_wanted output. Change the Inject value to 22.0, publish again, and check that the result becomes false. Click the edge to inspect the temperature readings. Your first bit of automation is alive.

If nothing happens, open Issues and Logs in the dock. They show missing inputs, code errors and connection problems. See The flow editor for the controls and shortcuts.

Connect a real sensor

Replace the Inject node with an MQTT node:

Field	Value
Provides	`living_temperature`, type `float`
`broker_host`	your broker's hostname or IP, reachable from the engine
`topic`	the sensor's temperature topic

Publish the change. The Function now responds to sensor readings instead of the test value. If your sensor sends a JSON object such as {"temperature": 18.0}, set json_key to temperature.

An MQTT node with inputs is a sender and publishes to its configured topic; one with outputs only is a listener and subscribes. Add a sender only after checking the payload format your device expects. A relay may need ON and OFF rather than a boolean.

!!! tip "Keep the first test on screen"

Check both warm and cold readings before connecting an actuator. **Pause**
and **Step** let you inspect queued messages one at a time. A real heating
controller also needs appropriate limits and hysteresis.

The MQTT node needs the mqtt extra. Fluksio does not run a broker, so point the node at your own, such as Mosquitto.

Show it on a dashboard

Create a dashboard and add a gauge bound to house.living_temperature. Publish the dashboard to see the current reading. Dashboard controls can also publish messages, so choose their bindings with care.

See Dashboards and panels for widgets and pairing a wall tablet.

For longer-term history, add an InfluxDB node that consumes living_temperature. It needs the influx extra. Configure your server URL, organization, bucket, token and writes mapping. Store the token under Secrets and select it in the node's credential field. Node types has the write and query formats.

Fluksio does not run an InfluxDB server either. Use your own.

Run it long term

The container from compose.yml is fit for long-term use. It restarts with Docker, and /data holds everything it keeps: the database, the flows, secrets, artifacts and its Redis. Back up that volume. Compose names it fluksio_data.

The container speaks plain HTTP. For access from outside your network, put a reverse proxy with HTTPS and WebSocket support in front of it, such as Caddy, Traefik or nginx, or enroll with the portal. A Caddyfile for fluksio.example.com is one line:

fluksio.example.com {
	reverse_proxy localhost:8080
}

Set FRONTEND_HOST to https://fluksio.example.com and TZ to your timezone, such as Europe/Berlin. See Configuration for the other settings, which go under environment in compose.yml.

To update, pull the repository and rebuild:

git pull
docker compose up -d --build

5.4 KiB Raw Blame History