Self-host quick start

Preview

The Towertail server is in an early stage. The Mac app works without it. You need the server only if samplers push their data to one central place.

The server receives samples from samplers in push mode. It keeps the time series in ClickHouse and evaluates the thresholds. The Mac app reads the data from the server over a REST and WebSocket API.

The Docker Compose stack has three services:

Service	What it does
server	The Towertail server. It listens on port 8080, on 127.0.0.1 only.
clickhouse	Keeps the metrics.
caddy	Terminates TLS on ports 80 and 443, and sends requests to the server.

Requirements

• A host with Docker and Docker Compose.
• Git, to get the source. The stack builds the server image from the source.

Start the stack

1. Get the source and go to the Docker folder:

   git clone https://github.com/towertail/towertail.git
   cd towertail/server/docker

2. Write a strong ClickHouse password to the secret file:

   openssl rand -hex 32 > secrets/ch_password

3. Build and start the stack:

   docker compose up -d --build

4. Make sure that the server is up:

   curl http://127.0.0.1:8080/healthz
   curl http://127.0.0.1:8080/readyz

   The /readyz endpoint returns 503 until the server connects to ClickHouse.

Then make a user token for the Mac app. Read Tokens.

Reach the server

Caddy serves the site towertail.local. To use this name on the host, add a line to /etc/hosts that points towertail.local to 127.0.0.1. For a real domain, edit caddy/Caddyfile.

Danger

The server itself uses plain HTTP on port 8080. Do not open port 8080 to the internet. Use Caddy for TLS.

Logs

docker compose logs -f server

The server writes JSON logs to stdout. Each change to a node or to the settings writes one log line with msg=audit.

Upgrade

1. Get the new source:

   git pull

2. Build and start the new server:

   docker compose up -d --build server

ClickHouse migrations apply automatically when the server connects. Mac apps and samplers connect again automatically.

Backup

The server keeps nodes, tokens and settings in one BoltDB file, config.db, in the server-data volume. Copy this file while the server is stopped. If you lose this file, you lose the configuration, but not the metrics.

For settings, read Configuration.