Cette page n'est pas encore disponible en français. Vous lisez la version anglaise.

Install Watchflare Hub on Linux

Install Watchflare Hub as a systemd service on Linux. Covers TimescaleDB via Docker, binary download for amd64 and arm64, and service hardening.

The Hub is distributed as a pre-built binary for Linux (x86_64 and arm64). This guide walks through installing it as a systemd service with TimescaleDB running in Docker.

Tip

Prefer containers? Deploy with Docker Compose gets you running in under 5 minutes with no manual setup.

Prerequisites

Linux x86_64 (amd64) or arm64
systemd
Docker (for TimescaleDB) — or an existing TimescaleDB instance
Two open ports: 8080 (dashboard) and 50051 (agent gRPC)

1. Start TimescaleDB

The Hub requires TimescaleDB for storage. The simplest way is to use the provided Compose file:

curl -O https://raw.githubusercontent.com/watchflare-io/watchflare/main/docker-compose-postgres.yml

Generate a database password and start the container:

echo "POSTGRES_PASSWORD=$(openssl rand -base64 32)" > .env
docker compose -f docker-compose-postgres.yml up -d

Note

Already running TimescaleDB? Skip this step and point POSTGRES_HOST at your existing instance. For other setup options, see the TimescaleDB documentation.

2. Download the binary

Download and install the latest release:

TAG=$(curl -s https://api.github.com/repos/watchflare-io/watchflare/releases/latest \
  | grep '"tag_name"' | cut -d'"' -f4)
VERSION=${TAG#v}  # strip leading 'v' for the filename
ARCH=amd64  # or arm64

curl -L "https://github.com/watchflare-io/watchflare/releases/download/${TAG}/watchflare-hub_${VERSION}_linux_${ARCH}.tar.gz" \
  | tar xz
sudo mv watchflare-hub /usr/local/bin/
sudo chmod +x /usr/local/bin/watchflare-hub

3. Create a dedicated user (recommended)

Running the Hub as a system user limits its access to the rest of the server.

sudo useradd --system --no-create-home --shell /sbin/nologin watchflare
sudo mkdir -p /var/lib/watchflare
sudo chown watchflare:watchflare /var/lib/watchflare

If you skip this step, remove User=watchflare from the service file in step 5.

4. Configure

Create the environment file. The Hub reads it at startup.

sudo mkdir -p /etc/watchflare

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=watchflare
POSTGRES_PASSWORD=your-db-password
POSTGRES_DB=watchflare

JWT_SECRET=your-32-char-secret
NOTIFICATION_ENCRYPTION_KEY=your-32-char-secret

ENV=production
TRUSTED_PROXIES=127.0.0.1,::1

# TLS_MODE=auto         # default — auto-generates a self-signed CA for gRPC
# COOKIE_SECURE=true    # enable if the Hub is behind an HTTPS reverse proxy
# COOKIE_DOMAIN=watchflare.example.com

Generate secrets with openssl rand -base64 32.

Lock down the file:

sudo chown root:watchflare /etc/watchflare/hub.env
sudo chmod 640 /etc/watchflare/hub.env

5. Install the systemd service

Create the service file:

[Unit]
Description=Watchflare Hub
Documentation=https://docs.watchflare.io
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=watchflare
EnvironmentFile=/etc/watchflare/hub.env
ExecStart=/usr/local/bin/watchflare-hub
Restart=always
RestartSec=5s
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/watchflare

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now watchflare-hub

6. Verify

sudo systemctl status watchflare-hub

Then open http://your-host:8080. The first visit redirects to account creation.

Updating

See Update the Hub for the full update procedure with backup steps and rollback instructions.

The Hub binary is also available for macOS (arm64/amd64) but a dedicated macOS service install is not documented. For local development, run the binary directly or use Docker Compose.