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:

```sh
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](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. From another machine on your network, open `http://<host-ip>:8080`.

Keep your own settings in a `compose.override.yml` next to `compose.yml`.
Compose reads both, and `git pull` leaves your file alone. Set `FRONTEND_HOST`
there to the address you open, since links for wall panels and mails are built
from it:

```yaml
services:
  fluksio:
    environment:
      FRONTEND_HOST: http://192.168.1.20:8080
```

Apply a change with `docker compose up -d`. To use another port, replace the
`ports` list. Without `!override`, Compose would add the port next to 8080:

```yaml
    ports: !override
      - "9000:8000"
```

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.override.yml` and rebuild:

```yaml
    build:
      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 devices](../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 database 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.

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](../interface/portal.md).
For example, a Caddyfile can proxy your app address:

```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.override.yml`.

To update, pull the repository and rebuild:

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