Docs · Deploy

Deployment

The development candidate is designed for a single self-hosted node bound to loopback. Production deployment guidance remains intentionally conservative.

Build and start

go build -o watchpost ./cmd/watchpost
./watchpost --host 127.0.0.1 --port 7334 --data-dir /var/lib/watchpost

Do not run as root. Give the service account write access only to its data directory. The included packaging/watchpost.service is a starting point that must be reviewed for your paths and operating system.

The default listener is loopback 127.0.0.1:7334. --host/--port and WATCHPOST_HOST/WATCHPOST_PORT override it (CLI > environment > default; a --host 0.0.0.0 or WATCHPOST_HOST=0.0.0.0 binding exposes the port on all IPv4 interfaces and is intended only for controlled networks). The legacy single-address --listen flag and WATCHPOST_LISTEN environment remain supported and cannot be combined with the explicit host/port form.

Run Watchpost as a machine service

To keep the server running unattended and boot-safely on a systemd host, install it as a system service. The first install requires root and creates the dedicated unprivileged watchpost account, /var/lib/watchpost, the unit, and (optionally) the protected /etc/watchpost/watchpost.env configuration file:

sudo watchpost service install
# Optional install flags:
#   --host HOST
#   --port PORT
#   --listen HOST:PORT
#   --data-dir DIRECTORY
#   --secure-cookies
#   --env-file FILE
sudo watchpost service install --host 127.0.0.1 --port 7404
sudo watchpost service start
sudo watchpost service stop
sudo watchpost service restart
watchpost service status
watchpost service logs
watchpost service logs --follow
sudo watchpost service uninstall

• The system unit is written to /etc/systemd/system/watchpost.service and managed with systemctl and journalctl --unit watchpost.service.
• It starts at boot with WantedBy=multi-user.target and does not depend on any user login or on systemd lingering.
• New units record the canonical --host/--port pair in ExecStart so the recorded listener is the runtime listener across restart and reboot; existing units installed with the legacy --listen form keep their listener until reinstalled. status reports enabled/running state, PID, version, listen address and a live health check of the public GET /healthz endpoint, and exits nonzero when the service is failed or missing.
• Uninstall removes the service registration and preserves Watchpost data.

• Install is a transaction.
• Watchpost preserves the prior managed unit bytes and inspects the prior systemd enablement and activity before mutating anything.
• Only exactly-recreatable states are accepted — enablement enabled, enabled-runtime, disabled and activity active, inactive — and masked, static, linked, generated, transient, failed, reloading and other non-restorable states are refused before any file or lifecycle change; unmask or stop the service first.
• On a failure, rollback restores the prior unit bytes and reproduces the exact prior enablement and activity states, distinguishing persistent from runtime enablement so runtime-only enablement is restored without leaving a persistent link; a failed fresh install is stopped and disabled while the unit is still loaded, then removed and systemd is reloaded.
• A changed binary with an unchanged unit is recognised as a changed installation and the service is restarted.
• A byte-identical unit and binary already enabled and active is a genuine no-op.
• The complete lifecycle family matches the ecosystem convention: service install|uninstall|start|stop|restart|status|enable|disable|logs|update|rollback. service update ARTIFACT SHA256 replaces the binary with a checksum-verified artifact, preserves the prior running/stopped state and enablement, and retains rollback metadata; service rollback restores the previous version and its operational state.

• Because the machine service does not inherit your shell environment, provide WATCHPOST_* configuration (master key, setup tokens, network policy, retention) through an absolute, root-owned 0600, non-symlink environment file (default /etc/watchpost/watchpost.env) passed with service install --env-file; systemd reads it via EnvironmentFile= before the process drops to User=watchpost, so the service account cannot rewrite its own machine configuration.
• The path is recorded in the integrity-checked managed metadata and revalidated before start, restart and status.
• The generated unit keeps NoNewPrivileges, PrivateTmp, ProtectSystem=strict, ProtectHome=true and ReadWritePaths scoped to /var/lib/watchpost.

Install the Watchpost Agent

The separate agent currently packages supported Linux amd64/arm64 archives. The installer verifies SHA256SUMS before writing anything.

# Current user, no sudo (binary only)
curl -fsSL https://watchpost-ops.github.io/agent-install.sh | sh

# Deliberate machine-wide binary location (still binary only)
curl -fsSL https://watchpost-ops.github.io/agent-install.sh | sudo sh -s -- --system

The --system route installs the binary to /usr/local/bin/watchpost-agent and invokes the canonical Go service installer. The agent runs as a systemd system unit under a dedicated unprivileged watchpost-agent account with /var/lib/watchpost-agent data:

sudo watchpost-agent service install
# Optional install flags:
#   --host HOST
#   --port PORT
#   --listen HOST:PORT
#   --env-file FILE
sudo watchpost-agent service install --host 127.0.0.1 --port 7405
sudo watchpost-agent service start
sudo watchpost-agent service stop
sudo watchpost-agent service restart
watchpost-agent service status
watchpost-agent service logs
sudo watchpost-agent service uninstall

• The agent interface defaults to loopback 127.0.0.1:7335. --host/--port and WATCHPOST_AGENT_HOST/WATCHPOST_AGENT_PORT override it (CLI > environment > default; ports must be 1–65535 and values are trimmed).
• The legacy single-address --listen flag and WATCHPOST_AGENT_LISTEN environment remain supported and cannot be combined with the explicit host/port form.
• New units record the canonical --host/--port pair in ExecStart so the recorded listener is the runtime listener across restart and reboot; existing units installed with the legacy --listen form keep their listener until reinstalled, and a bare reinstall or upgrade preserves the recorded listener.
• The agent is deliberately unprivileged: its telemetry (CPU, memory, load, uptime, filesystem) is read from world-readable /proc files and statfs(), which needs no root. service install --env-file preserves the agent's exposure/security settings (WATCHPOST_AGENT_EXPOSE, secure cookies, CIDR policy, setup token file) through a root-owned 0600 /etc/watchpost-agent/watchpost-agent.env; remote agent exposure remains experimental. service update ARTIFACT SHA256/service rollback preserve the installed listen address, environment file and prior operational state, and service uninstall removes the service registration while retaining private agent state and the installed binary.

Boot and recovery

Both the Watchpost server and Agent run as systemd system units (WantedBy=multi-user.target), so they start at boot without any user login and without systemd lingering. The unit records the absolute path of its executable at install time; moving or deleting that binary breaks the service until you reinstall.

Reverse proxy boundary

Keep Watchpost on loopback and terminate HTTPS at a reviewed reverse proxy. Preserve the original host and scheme, apply request-size and timeout limits, and do not expose health or diagnostics more broadly than intended.

Backups

Stop Watchpost before copying its SQLite data directory in this development version. A filesystem copy taken during writes is not a supported online backup. Test restoration into a separate directory before relying on a backup.

Upgrades

Database migrations run at startup. Before any future production upgrade, preserve the old binary and a tested backup, then verify startup, authentication, post counts, evidence counts, and representative history queries.

Fleet deployment

Each paired Watchpost remains independently useful and holds a separate secret. Pairing is not a reason to expose the federation endpoint publicly without TLS, network policy, rate control, and key-rotation procedures.