Guides

Install

Install Roastwarden from scratch: one container on a Raspberry Pi or any Linux host, the built-in MQTT broker, and the first sign-in.

Roastwarden runs on a small Linux computer on the same network as your roaster: a Raspberry Pi 4 or 5, an old laptop, a home server. The roaster talks to it, and any browser on the network, phones included, opens the dashboard. This guide installs it as one container: the server with its own MQTT broker, so nothing else is needed beside Docker.

Already run an MQTT broker (Home Assistant's, Mosquitto)? Use docker-compose.yml instead and point the server at your broker (the variables table in the README), or let the compose file start Mosquitto beside it. Everything else below is the same.

What you need

• A Raspberry Pi 4 or 5 with Raspberry Pi OS 64-bit (or any Linux machine, amd64 or arm64), on the roaster's network, with a fixed address (a DHCP reservation in your router).
• Docker with the compose plugin: curl -fsSL https://get.docker.com | sh, then sudo usermod -aG docker $USER and sign in again.
• A roaster that speaks one of Roastwarden's protocols. An ESP32 roaster over Wi-Fi uses MQTT, which this install provides; serial (TC4), Modbus, WebSocket and Phidgets boards connect too (connect your roaster).

1. Get the release

Each release on the project's releases page carries roastwarden-compose-vX.Y.Z.tar.gz, with the compose files pinned to that version:

mkdir ~/roastwarden && cd ~/roastwarden
tar xzf ~/Downloads/roastwarden-compose-vX.Y.Z.tar.gz --strip-components=1
cp .env.example .env

While the image's registry is private (until the public release), sign in to it first with docker login <registry>.

2. Name your roaster and give it a password

Every roaster signs in to the broker with its device id and a password of its own. Pick an id (letters, digits, _; it is the roaster's name in Roastwarden and in its MQTT topics) and make a password:

openssl rand -hex 16

Put both in .env, as id:password; more roasters are separated by commas:

MQTT_DEVICES=my_roaster:3f9c0e1b2a7d4c6e8f00112233445566

Nothing else in .env is required. Optional: ROASTWARDEN_READS=open lets anyone on your network read the dashboard without signing in (writes still need the owner key or a token); the default, login, asks each browser once.

3. Start it

The server runs as user 999 and keeps everything in data/: make the folder for it first.

mkdir -p data && sudo chown 999:999 data
docker compose -f docker-compose.single.yml up -d
docker logs roastwarden

The log prints the owner key once, at the first start: keep it in a password manager (it is also saved as data/owner.key). It is what signs a browser in and makes tokens for scripts and agents.

Open http://<the Pi's address>:8080 and sign in with the key. The first run asks what kind of roasting you do (home, enthusiast, roastery), your units and time zone, then opens Roasters → Add.

4. Connect the roaster

Set the roaster's firmware to the Pi's address, port 1883, user name = its device id, and the password from .env. For the ESP32 example sketch that is MQTT_HOST, DEVICE_ID and MQTT_PASSWORD at its top (connect your roaster). A second after it starts sending, it appears under Roasters → Found, not added yet; Set up adds it, and Check says whether it meets the standard.

Not appearing? docker exec roastwarden roast status lists the roasters heard and which may sign in to the broker. A roaster added to MQTT_DEVICES later needs a restart to sign in: docker compose -f docker-compose.single.yml up -d (a running roast waits: see "Updating").

Home Assistant: set MQTT_HOME_ASSISTANT_PASSWORD in .env (and restart) for Home Assistant's MQTT integration to sign in to this broker as homeassistant, then switch it on under Settings → Home Assistant (Home Assistant).

5. Updating

docker exec roastwarden roast busy --wait 60     # waits while a roast, drive or cooling runs
docker compose -f docker-compose.single.yml pull
docker compose -f docker-compose.single.yml up -d

A newer release's bundle pins the newer version: unpack it over the folder (your .env and data/ stay), then the same two compose commands. The database migrates itself at start.

Backups

The server copies its database every night into data/backups/ and keeps the newest ones (Settings → Backups; running it has the restore). Copy data/ somewhere else now and then: a dead SD card takes the copies with it.

Good to know

• Ports. The container uses the machine's own network (mDNS finds roasters on the LAN): 8080 for the dashboard, 1883 for MQTT. Something else on 1883 already (Mosquitto, Home Assistant's broker)? Set ROASTWARDEN_BROKER_ADDR=0.0.0.0:1884 in .env and give the roaster that port, or use your broker instead (see the top). Never forward either port to the internet; for access from outside, use a VPN (WireGuard, Tailscale).
• Safety. The roaster's firmware stops its heater when it loses the broker. With the broker inside the server that also covers the server stopping, but not a server that hangs while its broker still answers; a separate Mosquitto with the server's last will covers that too (security).
• Artisan. Roastwarden can be a screen for Artisan over Modbus TCP (Artisan as a screen); in this install use port 1502 (ROASTWARDEN_MODBUS_ADDR=0.0.0.0:1502 in .env), as the container does not run as root.
• Links. Share pages, label QR codes and approval links start with the address the request came to. Opened from outside under another name (a VPN name, a proxy)? Set it in Settings → Roasting → Public address, or docker exec roastwarden roast settings set public_url=https://roast.example.com.
• Other settings go in .env too (the variables table in the README); restart with docker compose -f docker-compose.single.yml up -d after a change.
• Agents. The roast command line is in the image (docker exec roastwarden roast --help); for an agent, make a token in Settings → Tokens (agents).
• Where to go next: a tour of every feature, the user guide.