diff --git a/README.md b/README.md index 37f1cfe..227af98 100644 --- a/README.md +++ b/README.md @@ -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. --- diff --git a/deploy/sentio-smtp.service b/deploy/sentio-smtp.service index 98d6485..1fe9a91 100644 --- a/deploy/sentio-smtp.service +++ b/deploy/sentio-smtp.service @@ -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