app/docs/getting-started/facility-automation.md

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 on a 64-bit machine, x86 or ARM. A Raspberry Pi 4 or 5 with a 64-bit OS works too. Clone the app repository and start its single container. Replace <repository-url> with the app repository's URL:

git clone <repository-url> fluksio
cd fluksio
docker compose up -d
docker compose logs fluksio

The first build takes a few minutes, longer on a Raspberry Pi. 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 devices 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 database 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.

Run InfluxDB separately, just like the MQTT broker.

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 prefixes its name with your project name.

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. For example, a Caddyfile can proxy your app address:

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