6.5 KiB
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_temperaturewith typefloat. - Under Settings, set the
living_temperaturevalue to18.0and Interval to5seconds.
This gives you a pretend sensor. Add a Function node with:
- Consumes:
living_temperature, typefloat. - Provides:
heat_wanted, typebool.
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 input ports publishes to its configured topic; one with
output ports subscribes. Add a publishing node 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.