Install on Linux

Sentinel installs as a static binary and a hardened systemd service. Make sure the requirements are in place: a PostgreSQL database, DNS names and TLS certificates (or a TLS-terminating proxy). The installation takes about 15 minutes.

1. Create the user and directories

sudo useradd --system --home /var/lib/klipsu-sentinel --shell /usr/sbin/nologin klipsu-sentinel
sudo install -d -m 0755 /opt/klipsu-sentinel /etc/klipsu-sentinel
sudo install -d -m 0700 -o klipsu-sentinel -g klipsu-sentinel /var/lib/klipsu-sentinel

2. Install the binary and configuration

Use the linux_amd64 or linux_arm64 package to match your server.

sha256sum -c SHA256SUMS --ignore-missing       # verify the download
tar -xzf klipsu-sentinel_<version>_linux_amd64.tar.gz
cd klipsu-sentinel_<version>_linux_amd64
sudo install -m 0755 sentinel /opt/klipsu-sentinel/sentinel
sudo install -m 0640 -g klipsu-sentinel sentinel.example.yaml /etc/klipsu-sentinel/sentinel.yaml

Edit /etc/klipsu-sentinel/sentinel.yaml. At minimum set database.url, public_url, the listeners and the TLS files. Every key is explained in Configuration.

sudoedit /etc/klipsu-sentinel/sentinel.yaml

TIP

Keep the database password out of the file: put SENTINEL_DATABASE_URL=postgres://… in /etc/klipsu-sentinel/env (mode 0640, group klipsu-sentinel) and load it in step 4 with EnvironmentFile=.

3. Check and initialise

sudo -u klipsu-sentinel /opt/klipsu-sentinel/sentinel config check --config /etc/klipsu-sentinel/sentinel.yaml
sudo -u klipsu-sentinel /opt/klipsu-sentinel/sentinel init --config /etc/klipsu-sentinel/sentinel.yaml

config check validates the configuration and connects to the database. init:

• creates the key file /var/lib/klipsu-sentinel/sentinel.key;
• applies the database migrations;
• creates the organisation and the policy signing key;
• writes a one-time setup token, valid for 24 hours, to /var/lib/klipsu-sentinel/setup-token.

IMPORTANT

Back up sentinel.key now, offline and separately from database backups. See Keys and secrets.

4. Start the service

sudo cp deploy/klipsu-sentinel.service /etc/systemd/system/
sudo systemctl edit klipsu-sentinel     # optional: [Service] EnvironmentFile=/etc/klipsu-sentinel/env
sudo systemctl daemon-reload
sudo systemctl enable --now klipsu-sentinel
sudo journalctl -u klipsu-sentinel -f

The unit runs Sentinel as klipsu-sentinel with a read-only system, where only /var/lib/klipsu-sentinel is writable. It can bind ports below 1024 and restarts on failure.

Check that it is ready:

curl -fsS https://sentinel.example.com/readyz

Next steps

Continue with First-time setup.