Fix the manual install instructions

Ran them on a clean Ubuntu host. Steps 1, 2, 4 and 5 were correct;
the rest were not.

- PostgreSQL 18 is a hard floor because the schema calls uuidv7(), a v18
  builtin. On 16 the migration dies with "function uuidv7() does not
  exist", which explains nothing. Said so, with the symptom.
- Step 3 used createuser --pwprompt, which is interactive and never
  mentioned that the password has to match database.url. Added the
  scriptable form.
- Step 6 told you to run ./target/release/sentio-smtp and then setcap
  /usr/local/bin/sentio-smtp, a path that does not exist until step 7.
- Step 7 could not work: the unit ran as User=sysop with
  WorkingDirectory=/home/sysop/sentio and read
  /etc/sentio/production.toml, none of which the README creates. It also
  had redis-server in both Requires= and Wants= with contradictory
  comments.

The unit now runs as a sentio user the README creates, reads the config
path step 5 writes, and separates hard dependencies from optional ones.
This commit is contained in:
Truespar Team
2026-08-24 12:23:33 +02:00
parent 7d2bc7059f
commit ef76f5dd06
2 changed files with 56 additions and 26 deletions
+39 -5
View File
@@ -182,15 +182,28 @@ docker compose down -v # stop and delete all volumes
| Service | Default address | Purpose |
|---|---|---|
| PostgreSQL 18 | `localhost:5432` | All persistent state |
| PostgreSQL 18+ | `localhost:5432` | All persistent state |
| Redis or Valkey | `localhost:6379` | Rate limits, bans, greylist, reputation |
| NATS with JetStream | `localhost:4222` | Delivery, retry, webhook, and event pipelines |
| S3-compatible storage | `localhost:9000` | Raw `.eml` and attachment blobs |
PostgreSQL 18 is a hard floor: the schema uses `uuidv7()`, which arrived as a
built-in in 18. On an older server the migration stops with
`function uuidv7() does not exist`, which does not otherwise explain itself.
Check with `psql -tAc 'SHOW server_version'` before you start.
Any S3-compatible endpoint works - AWS S3, Cloudflare R2, MinIO, SeaweedFS,
Ceph. For NATS, JetStream must be enabled (`nats-server -js`); Sentio creates
its own streams on startup.
All four are required, and Sentio exits at startup if the KV store or the queue
is unreachable. Install them before step 6, or run just those four from the
compose file and keep Sentio itself on the host:
```bash
docker compose up -d postgres redis nats minio
```
**Optional services** - Sentio degrades gracefully if these are absent.
| Service | Default address | Without it |
@@ -237,6 +250,15 @@ sudo -u postgres createuser --pwprompt sentio
sudo -u postgres createdb --owner=sentio sentio
```
`--pwprompt` asks for a password interactively. It has to match the one in
`database.url`, which ships as `sentio`. To script it, or to use a different
password, set both together:
```bash
sudo -u postgres psql -c "CREATE ROLE sentio LOGIN PASSWORD 'sentio';"
sudo -u postgres createdb --owner=sentio sentio
```
### 4. Apply migrations
The binary embeds its migrations and applies them in order:
@@ -266,18 +288,26 @@ credentials. See [Configuration](#configuration).
./target/release/sentio-smtp --config /etc/sentio/sentio.toml serve
```
This needs PostgreSQL, Redis, NATS and the object store already running - see
[Requirements](#requirements).
Binding ports below 1024 as a non-root user needs the capability rather than
root:
root. Grant it on whichever copy you are running:
```bash
sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/sentio-smtp
sudo setcap 'cap_net_bind_service=+ep' target/release/sentio-smtp
```
Under systemd this is unnecessary - the unit grants
`AmbientCapabilities=CAP_NET_BIND_SERVICE` instead.
### 7. Run as a service
A unit file is included at [`deploy/sentio-smtp.service`](deploy/sentio-smtp.service):
```bash
sudo useradd --system --home-dir /var/lib/sentio --shell /usr/sbin/nologin sentio
sudo install -d -o sentio -g sentio /var/lib/sentio
sudo cp target/release/sentio-smtp /usr/local/bin/
sudo cp deploy/sentio-smtp.service /etc/systemd/system/
sudo systemctl daemon-reload
@@ -285,8 +315,12 @@ sudo systemctl enable --now sentio-smtp
journalctl -u sentio-smtp -f
```
Review the unit's `Requires=`/`After=` lines first - they assume the supporting
services run on the same host.
The unit runs as the `sentio` user created above and reads
`/etc/sentio/sentio.toml`, so make that file readable by it. Check the
`Requires=`/`After=` lines before enabling: they name `postgresql.service`,
`nats.service` and `redis-server.service`, and systemd refuses to start a unit
whose `Requires=` target does not exist. Drop or rename any you run
differently - in a container, on another host, or under a different unit name.
---
+17 -21
View File
@@ -2,33 +2,27 @@
Description=Sentio SMTP - Multi-tenant Email Platform
Documentation=https://github.com/truespar/sentio
# Hard dependencies - Sentio cannot start without these. systemd will
# refuse to start sentio-smtp if any of these fail to come up, and will
# pull them down if sentio-smtp is stopped.
# Hard dependencies. Sentio exits at startup if the KV store or the queue is
# unreachable, so there is no point starting before they are up.
Requires=postgresql.service nats.service redis-server.service
# Soft dependencies - Sentio runs without them but loses features:
# redis-server → rspamd backing store (history, ratelimit, replies)
# rspamd → spam scoring (sentio falls back to its builtin scorer)
# clamav-daemon → virus scanning of attachments / inbound
Wants=redis-server.service rspamd.service clamav-daemon.service
# Start order: only after the deps above are ready and the network is up.
After=network-online.target postgresql.service nats.service redis-server.service rspamd.service clamav-daemon.service
# Optional. Sentio starts without these and loses a feature each:
# rspamd -> spam scoring falls back to the builtin scorer
# clamav-daemon -> attachments are not virus-scanned
Wants=rspamd.service clamav-daemon.service
Wants=network-online.target
After=network-online.target postgresql.service nats.service redis-server.service rspamd.service clamav-daemon.service
[Service]
Type=simple
# Account that owns the build directory and the production config. The
# config file (/etc/sentio/production.toml) must be readable by this
# group (recommend root:sysop 640).
User=sysop
Group=sysop
WorkingDirectory=/home/sysop/sentio
# Create this account before enabling the unit:
# sudo useradd --system --home-dir /var/lib/sentio --shell /usr/sbin/nologin sentio
User=sentio
Group=sentio
# Production config holds DB / Redis / S3 / NATS credentials.
ExecStart=/usr/local/bin/sentio-smtp --config /etc/sentio/production.toml
ExecStart=/usr/local/bin/sentio-smtp --config /etc/sentio/sentio.toml
# No ExecReload: Sentio has no SIGHUP handler, so a reload signal would
# terminate the process (libc default). certbot's post-renewal hook uses
# `systemctl reload-or-restart`, which without ExecReload falls through
@@ -39,9 +33,11 @@ RestartSec=5
# Sandboxing
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/var/log /tmp
ProtectHome=true
PrivateTmp=true
# ProtectSystem=strict makes everything outside these read-only. Add
# /etc/sentio/acme here too if you enable the built-in ACME client.
ReadWritePaths=/var/lib/sentio
# Bind privileged ports 25 / 465 / 587 as a non-root user.
AmbientCapabilities=CAP_NET_BIND_SERVICE