Files

T

stroblme c9fda50601 Connection nodes speak of listener and sender, and of send_queue_size

mqtt and http take websocket's vocabulary: their Mode is LISTENER/SENDER,
default names read mqtt_listener_… and http_listener_…, and mqtt's
publish_queue_size is send_queue_size. No alias stays behind, so the flow
store rewrites the old setting in every published and draft mqtt node when it
opens, in the same migration as trigger → debounce. Every mqtt and http
setting carries a one-line description for the editor, and the node-types
reference uses one wording for direction and says that an http sender
publishes a JSON object response on its outputs.

2026-10-15 09:44:22 +02:00

6.6 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 the Docker stack

You need Git, Docker with Compose v2, make, and openssl. Port 80 must be free. Clone the public app repository and run its commands from the repo root:

git clone https://git.stroblme.de/Fluksio/app.git fluksio
cd fluksio
make init
make dev-local

make init creates .env, generates secrets, creates the proxy network, and prints your admin login. It is safe to run again: existing secrets stay as they are.

Give the containers a moment to start on the first build, then open http://app.localhost. Sign in with the admin login: adding Python code requires a superuser account. The API is at http://api.localhost, and the docs are at http://docs.localhost.

For a Docker instance reached from another machine on your network, use:

make dev-lan

Open http://<host-ip>:8080. Choose another port with make dev-lan APP_PORT=8081. This is a development stack; see running it long term before using it for a deployment.

When you are done, stop the stack with make down. Your data volumes stay in place 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.

Docker development stacks include a test broker at mosquitto:1883; it has no published host port, so your physical sensors cannot reach it directly. For real sensors, use your own broker. The Docker image includes the MQTT and InfluxDB connector dependencies.

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

The Docker development stack includes an InfluxDB test service at http://influxdb:8086, with organization and bucket fluksio and token fluksio-dev-token. It is for testing; configure a persistent InfluxDB server for data you want to keep. The production stack includes neither InfluxDB nor an MQTT broker.

Run it long term

For a Docker deployment, run make init, then edit the repository's .env:

Setting	Example
`DOMAIN`	`example.com`
`ENVIRONMENT`	`production`
`FRONTEND_HOST`	`https://app.example.com`
`VITE_API_URL`	`https://api.example.com`
`BACKEND_CORS_ORIGINS`	`https://app.example.com`
`FIRST_SUPERUSER`	your administrator email
`TZ`	your timezone, such as `Europe/Berlin`

Keep the generated secrets. Stop any development stack with make down. Set up DNS and a reverse proxy with HTTPS and WebSocket support before running make up. That target starts the application services; it requires a proxy on the Docker proxy network. Route app.example.com to fluksio-app:80, api.example.com to fluksio-api:8000 and, optionally, docs.example.com to fluksio-docs:80.

docker/compose.traefik.yml is an optional proxy configuration. It also needs EMAIL, USERNAME and HASHED_PASSWORD for certificates and dashboard authentication; make init does not set these up.

The published port from make dev-lan uses HTTP. For access outside your network, use HTTPS or enroll with the portal.

Back up .env and both persistent volumes: app-flow-data holds the database, flows, secrets and artifacts; app-redis-data holds message values, node state and queued work. Compose prefixes volume names with the project name fluksio-app. Also back up any external MQTT or InfluxDB data you need.

Next steps

Flows, nodes and messages: how the graph works.
Secrets, modules and alerts: credentials and notifications.
Remote workers: run node code on another machine.
Configuration: settings and storage paths.

6.6 KiB Raw Blame History