docs
This commit is contained in:
@@ -1,325 +1,164 @@
|
||||
# Getting started: facility automation
|
||||
|
||||
You have a box in a cupboard, a handful of sensors that already publish
|
||||
somewhere, and an ambition to make the house do something about them. This
|
||||
page brings up a Fluksio instance you can leave running for years, then wires
|
||||
the first sensor through to a dashboard.
|
||||
Build a small temperature flow, then connect a real sensor when you're ready.
|
||||
No hardware required for the first lap.
|
||||
|
||||
Budget an afternoon. Most of it is the browser, which is the point: you will be
|
||||
in this interface a lot, so it is worth learning it properly.
|
||||
## Start the Docker stack
|
||||
|
||||
## What you are standing up
|
||||
|
||||
```text
|
||||
sensors ──MQTT──▶ ┌──────────────┐ ──▶ InfluxDB (history)
|
||||
│ Fluksio │
|
||||
HTTP / webhooks ──▶│ flow engine │ ──▶ dashboards (what you look at)
|
||||
│ │
|
||||
schedules ────────▶└──────────────┘ ──▶ MQTT / HTTP (what you control)
|
||||
│
|
||||
└── workers on other boxes (optional)
|
||||
```
|
||||
|
||||
One engine holds every flow. Nothing here is a plugin you install separately:
|
||||
the broker client, the time-series writer, the dashboards and the alerting are
|
||||
all part of the same process, editing the same graph.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Docker and Compose v2 on the host
|
||||
- The address you will type into a browser. On a home network that is the
|
||||
server's own address, `192.168.1.50`, and nothing else is needed. A
|
||||
hostname is optional, and covered below
|
||||
- Optionally: an MQTT broker and an InfluxDB you already run. If not, the stack
|
||||
can start both for you
|
||||
|
||||
## Set it up
|
||||
|
||||
Clone the app repository and try it on the machine you are sitting at:
|
||||
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:
|
||||
|
||||
```sh
|
||||
git clone https://git.stroblme.de/Fluksio/app.git ~/fluksio
|
||||
cd ~/fluksio
|
||||
make init # once: .env with generated secrets, `proxy` network, prints the admin login
|
||||
make dev-local # full stack at http://app.localhost (API at http://api.localhost)
|
||||
make down # stop it
|
||||
git clone https://git.stroblme.de/Fluksio/app.git fluksio
|
||||
cd fluksio
|
||||
make init
|
||||
make dev-local
|
||||
```
|
||||
|
||||
`make dev-local` needs port 80 free and only answers on `localhost`; the
|
||||
sections below make it reachable from other machines. `make init` is safe to
|
||||
run again: it only fills secrets still set to `changethis`, and `.env`
|
||||
otherwise stays as you left it.
|
||||
`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.
|
||||
|
||||
For an instance you leave running, edit `.env` first (`FIRST_SUPERUSER`,
|
||||
`ENVIRONMENT=production`). It is the whole configuration. The four settings that matter on day one:
|
||||
Give the containers a moment to start on the first build, then open
|
||||
[http://app.localhost](http://app.localhost). Sign in with the admin login:
|
||||
adding Python code requires a superuser account. The API is at
|
||||
[http://api.localhost](http://api.localhost), and the docs are at
|
||||
[http://docs.localhost](http://docs.localhost).
|
||||
|
||||
| Setting | What it does |
|
||||
|---|---|
|
||||
| `DOMAIN` | the hostname everything is served under, if you use one. Left alone it only names the issuer that agents authenticate against |
|
||||
| `FIRST_SUPERUSER` | the account you sign in with |
|
||||
| `FIRST_SUPERUSER_PASSWORD` | generated by `make init`; it prints it, and it stays in `.env` |
|
||||
| `ENVIRONMENT` | `production` closes the interactive API schema; `local` leaves it open |
|
||||
|
||||
Everything the instance owns (the database, your flows, secrets, artifacts,
|
||||
the packages your node code imports) is on one Docker volume.
|
||||
Backing that volume up is backing up the instance.
|
||||
|
||||
??? note "Even smaller: no Docker at all"
|
||||
|
||||
`pip install fluksio && fluksio serve` gives you the same engine with no
|
||||
containers, keeping its data in `~/.fluksio`. What it does not give you is
|
||||
the web interface, which the SPA container serves, so you would drive it
|
||||
from the API, or [pair it with a portal](../interface/portal.md) that
|
||||
serves the dashboard for you. Good for a Raspberry Pi that only runs flows;
|
||||
less good as your main instance.
|
||||
|
||||
## Reach it from another machine
|
||||
|
||||
Start it one of two ways, depending on whether you have a hostname to point at
|
||||
it. Neither is more supported than the other.
|
||||
|
||||
### On your own network, by address
|
||||
|
||||
The usual case: the box is in a cupboard at `192.168.1.50` and you open it from
|
||||
a laptop. Layer `docker/compose.lan.yml` on, which publishes the interface on a
|
||||
port and serves the API from that same origin:
|
||||
For a Docker instance reached from another machine on your network, use:
|
||||
|
||||
```sh
|
||||
APP_PORT=8080 docker compose -p fluksio-app --env-file .env \
|
||||
-f docker/compose.yml -f docker/compose.lan.yml up -d --build
|
||||
make dev-lan
|
||||
```
|
||||
|
||||
Open `http://192.168.1.50:8080`. That one address is the whole application:
|
||||
the interface, the API under `/api`, and the websocket that puts live values on
|
||||
the canvas.
|
||||
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](#run-it-long-term) before using it for a deployment.
|
||||
|
||||
Nothing in that URL is configured anywhere. The interface is built to address
|
||||
the API relative to whatever origin served the page, so the same containers
|
||||
answer to the machine's address, to a hostname you add later, and through an
|
||||
ssh tunnel, without being rebuilt. It is also why no CORS list needs
|
||||
maintaining: the browser is talking to one origin.
|
||||
|
||||
!!! danger "This is your network, not the internet"
|
||||
|
||||
A published port is plain HTTP with no certificate. Between your own
|
||||
machines that is fine, and it is not something to forward from a router. To
|
||||
reach the house from outside, put a reverse proxy with TLS in front of it,
|
||||
or [pair it with a portal](../interface/portal.md), which needs no inbound
|
||||
route at all.
|
||||
|
||||
### With a hostname, behind a reverse proxy
|
||||
|
||||
If you have DNS, or want certificates, set `DOMAIN` and run `make up`
|
||||
instead. The interface is then served on `app.${DOMAIN}` and the API on
|
||||
`api.${DOMAIN}`, and nothing is published on a host port.
|
||||
|
||||
The stack emits Traefik labels and ships a Traefik you can bring up alongside
|
||||
it (`docker/compose.traefik.yml`). With Nginx Proxy Manager or Caddy instead,
|
||||
attach it to the `proxy` network and forward `app.${DOMAIN}` →
|
||||
`fluksio-app:80` and `api.${DOMAIN}` → `fluksio-api:8000`.
|
||||
|
||||
!!! tip "Developing on the same machine"
|
||||
|
||||
`make dev-lan` is `make dev-local` plus the published port: the app on
|
||||
`http://<host-ip>:8080`, `APP_PORT` to move it. `make dev-local` recreates
|
||||
the stack without that port, so re-run `make dev-lan` after one.
|
||||
|
||||
## Sign in
|
||||
|
||||
Open whichever address you chose (`http://app.localhost` for `make dev-local`)
|
||||
and sign in with the login `make init` printed. You should be looking at Home:
|
||||
an empty brain graph, a health summary, and a flow list with nothing in it.
|
||||
When you are done, stop the stack with `make down`. Your data volumes stay
|
||||
in place for the next start.
|
||||
|
||||
## Your first flow
|
||||
|
||||
Go to **Flows → New flow** and call it `house`. You land on the canvas.
|
||||
Open **Flows**, create a flow named `house`, and use **Add node** to add an
|
||||
**Inject** node. In its panel:
|
||||
|
||||
A flow is a set of nodes that talk to each other through **named messages**.
|
||||
You do not draw wires: a node says which messages it needs and which it
|
||||
produces, and the canvas draws the graph that follows. Renaming is safe, fan-in
|
||||
is free, and two flows share a value by naming it.
|
||||
- Under **Provides**, add `living_temperature` with type `float`.
|
||||
- Under **Settings**, set the `living_temperature` value to `18.0` and
|
||||
**Interval** to `5` seconds.
|
||||
|
||||
### Read a sensor
|
||||
This gives you a pretend sensor. Add a **Function** node with:
|
||||
|
||||
Press **Add node** (or ⌘P / Ctrl-P, which opens the command palette) and pick
|
||||
**MQTT**. In its panel on the right:
|
||||
- **Consumes**: `living_temperature`, type `float`.
|
||||
- **Provides**: `heat_wanted`, type `bool`.
|
||||
|
||||
- **Broker host** — your broker's hostname, `mosquitto` if you are using the
|
||||
one the stack can start
|
||||
- **Topic** — map each output to a topic:
|
||||
`{"living_temperature": "zigbee2mqtt/living/temperature"}`
|
||||
- **Provides** — add one output port named `living_temperature`, type `float`
|
||||
|
||||
That is a working node. Press **Publish** (⌘S) and the engine picks it up.
|
||||
|
||||
The canvas now draws your node with a live value on its output as soon as the
|
||||
broker sends one. Click the wire to see the last payload and its history.
|
||||
|
||||
### Do something with it
|
||||
|
||||
Add a **Function** node. This is a Python node, and the code editor opens in
|
||||
its panel:
|
||||
In the code editor, enter:
|
||||
|
||||
```python
|
||||
def process(living_temperature, comfortable=21.0):
|
||||
"""Ask for heat when the room is below the comfort point."""
|
||||
return {"heat_wanted": living_temperature < comfortable}
|
||||
def process(living_temperature):
|
||||
return {"heat_wanted": living_temperature < 21.0}
|
||||
```
|
||||
|
||||
Declare `living_temperature` as an input (type `float`) and `heat_wanted` as an
|
||||
output (type `bool`). `comfortable` is not a port but a **setting**,
|
||||
because it is a constant of this node rather than something the graph carries.
|
||||
It shows up as a field in the node's Settings section.
|
||||
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.
|
||||
|
||||
The canvas now draws MQTT → your function, because the message names line up.
|
||||
Nothing else was needed.
|
||||
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.
|
||||
|
||||
### Act on it
|
||||
If nothing happens, open **Issues** and **Logs** in the dock. They show missing
|
||||
inputs, code errors and connection problems. See [The flow editor](../interface/flow-editor.md)
|
||||
for the controls and shortcuts.
|
||||
|
||||
Add a second **MQTT** node, this time with `heat_wanted` as an *input*, and a
|
||||
topic mapping to whatever your relay listens on. A node with inputs publishes;
|
||||
a node with outputs subscribes.
|
||||
## Connect a real sensor
|
||||
|
||||
Publish the flow. You have a thermostat.
|
||||
Replace the Inject node with an **MQTT** node:
|
||||
|
||||
!!! warning "Test before it touches a relay"
|
||||
| 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 |
|
||||
|
||||
A flow can be **paused** (it holds messages instead of running them) and
|
||||
**stepped** (release exactly one). Together with the run button, which
|
||||
injects a value by hand, that is how you convince yourself the logic is
|
||||
right before the contactor finds out. Both live on the dock at the bottom
|
||||
of the canvas.
|
||||
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`.
|
||||
|
||||
## Store the history
|
||||
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.
|
||||
|
||||
A live value is enough to control something and useless for answering "was last
|
||||
February colder?". That is what the **InfluxDB** node is for.
|
||||
!!! tip "Keep the first test on screen"
|
||||
|
||||
Add one, and configure it to write the message you already have:
|
||||
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.
|
||||
|
||||
```json
|
||||
{
|
||||
"url": "http://influxdb:8086",
|
||||
"token": {"$secret": "influx-token"},
|
||||
"org": "home",
|
||||
"bucket": "sensors",
|
||||
"writes": {
|
||||
"living_temperature": {
|
||||
"measurement": "environment",
|
||||
"field": "temp_c",
|
||||
"tags": {"room": "living"}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
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.
|
||||
|
||||
Give it `living_temperature` as an input and every value that passes gets a
|
||||
point.
|
||||
## Show it on a dashboard
|
||||
|
||||
Note the token. Credentials never sit in a flow: `{"$secret": "influx-token"}`
|
||||
is a reference into an encrypted store, and the editor renders those fields as
|
||||
a secret picker. Add the actual value once under **Secrets**. Flows are a git
|
||||
repository you might well push somewhere, so this keeps a password out of it.
|
||||
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.
|
||||
|
||||
Reading back is the same node with `queries` instead of `writes`, or, for
|
||||
anything a chart asks for, a pair of small Python nodes on either side that
|
||||
build a Flux query and shape its rows. That indirection is deliberate: the
|
||||
database node holds the connection and nothing else, so a dashboard widget
|
||||
never learns which database answered it.
|
||||
See [Dashboards and panels](../interface/dashboards.md) for widgets and pairing
|
||||
a wall tablet.
|
||||
|
||||
## Put it on a screen
|
||||
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](../reference/node-types.md#influxdb)
|
||||
has the write and query formats.
|
||||
|
||||
**Dashboards → New dashboard**, then drag widgets onto the grid and bind each
|
||||
one to a message. A gauge on `house.living_temperature`, a switch on
|
||||
`house.heat_wanted`, a chart on the history.
|
||||
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.
|
||||
|
||||
Widgets are typed the same way ports are: a switch binds to a `bool`, a gauge
|
||||
to a number, an agenda to a `list`. Bind it wrong and the editor says so rather
|
||||
than drawing nothing.
|
||||
## Run it long term
|
||||
|
||||
Controls work in the other direction: a switch on a dashboard publishes the
|
||||
message it is bound to, exactly as a node would. The canvas draws it as a
|
||||
labelled endpoint feeding the nodes that read it, so a value never appears from
|
||||
nowhere.
|
||||
For a Docker deployment, run `make init`, then edit the repository's `.env`:
|
||||
|
||||
For a tablet on the wall, see [Dashboards and panels](../interface/dashboards.md):
|
||||
a panel is a named device, it pairs with a six-character code instead of a
|
||||
login, and it can only reach the dashboards you gave it.
|
||||
| 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` |
|
||||
|
||||
## Spread it across machines
|
||||
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`.
|
||||
|
||||
You now have one box doing everything. Two reasons to change that: something
|
||||
lives on a different network, or something needs hardware the engine's host
|
||||
does not have.
|
||||
`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 unit of distribution is the **worker**. It runs the code of nodes you mark
|
||||
for it, and it dials *out* to the engine, so the Pi in the shed does not need
|
||||
an inbound route, and the engine does not need to reach it.
|
||||
The published port from `make dev-lan` uses HTTP. For access outside your
|
||||
network, use HTTPS or [enroll with the portal](../interface/portal.md).
|
||||
|
||||
On the engine, mint a token:
|
||||
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.
|
||||
|
||||
```sh
|
||||
curl -X POST https://api.${DOMAIN}/api/v1/workers/tokens \
|
||||
-H "Authorization: Bearer $TOKEN" -d '{"name": "shed-pi", "labels": ["shed", "gpio"]}'
|
||||
```
|
||||
## Next steps
|
||||
|
||||
The labels are signed into it, so the worker can repeat them with `--labels`
|
||||
but not change them.
|
||||
|
||||
On the other machine, with that token in `FLUKSIO_WORKER_TOKEN`:
|
||||
|
||||
```sh
|
||||
pip install fluksio-worker
|
||||
fluksio-worker \
|
||||
--url wss://api.${DOMAIN}/api/v1/workers/attach \
|
||||
--labels shed,gpio \
|
||||
--parallel 2
|
||||
```
|
||||
|
||||
Then mark the node that talks to the shed's GPIO with `device: shed`, and it
|
||||
runs there. Everything else stays where it is. A node bound to a label no
|
||||
attached worker carries simply waits rather than failing, so you can write the
|
||||
flow before the hardware arrives.
|
||||
|
||||
!!! note "What a worker is not"
|
||||
|
||||
It is not a second engine. Subscriptions, schedules, webhooks and the
|
||||
dashboards all stay in one process, which keeps a value having one
|
||||
definition. A worker executes node bodies, nothing else. Scaling *the
|
||||
engine* to several processes is not supported: run one.
|
||||
|
||||
## Make it tell you when something breaks
|
||||
|
||||
Under **Alerts**, add a channel and a rule. Channels are ntfy (a push
|
||||
notification on your phone), SMTP, a webhook, or a message a dashboard
|
||||
notification widget reads.
|
||||
|
||||
What you probably want on day one is everything, to ntfy:
|
||||
|
||||
- add an ntfy channel with your server and topic
|
||||
- add a rule with no events ticked, which means *all of them*
|
||||
|
||||
The engine deduplicates aggressively, so the same node failing every second is
|
||||
one alert rather than thirty-six thousand, and caps the total at ten an hour
|
||||
however bad it gets. See [Secrets, modules and alerts](../interface/operations.md).
|
||||
|
||||
## Keep it alive
|
||||
|
||||
- **Back up the data volume.** That is the database, the flows, the secrets and
|
||||
the artifacts. Everything else is rebuildable.
|
||||
- **Watch Home.** The health summary names what is wrong — a quarantined flow, a
|
||||
node that will not load, a stalled queue, a flow that cannot run because its
|
||||
graph does not validate.
|
||||
- **Flows are git.** `git log` inside the flow store is the history of every
|
||||
change anyone made, and reverting one is a revert.
|
||||
|
||||
## Where to go next
|
||||
|
||||
- [Flows, nodes and messages](../concepts/flows.md) — the model, properly
|
||||
- [Node types](../reference/node-types.md) — everything you can put on a canvas
|
||||
without writing Python
|
||||
- [The flow editor](../interface/flow-editor.md) — the canvas, in detail
|
||||
- [Keeping state in a flow](../concepts/state.md) — running totals, debounces,
|
||||
and the one rule that makes them safe
|
||||
- [Accounts and the portal](../interface/portal.md) — reach the instance
|
||||
from outside the house without opening a port
|
||||
- [Flows, nodes and messages](../concepts/flows.md): how the graph works.
|
||||
- [Secrets, modules and alerts](../interface/operations.md): credentials and notifications.
|
||||
- [Remote workers](../code/workers.md): run node code on another machine.
|
||||
- [Configuration](../reference/configuration.md): settings and storage paths.
|
||||
|
||||
Reference in New Issue
Block a user