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. Clone the app repository and start
its single container:

```sh
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](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](../reference/configuration.md#image-options). Add the ones you need to
`EXTRAS` in `compose.yml` and rebuild:

```yaml
      args:
        EXTRAS: "mqtt,influx"
```

```sh
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:

```python
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](../interface/flow-editor.md)
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](../interface/dashboards.md) 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](../reference/node-types.md#influxdb)
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](../interface/portal.md). A
Caddyfile for `fluksio.example.com` is one line:

```text
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](../reference/configuration.md)
for the other settings, which go under `environment` in `compose.yml`.

To update, pull the repository and rebuild:

```sh
git pull
docker compose up -d --build
```