Configuration
Layout on the control plane
| Path |
What |
/etc/xvii/instance.env |
DOMAIN, ACME_EMAIL, CLOUDFLARE_API_TOKEN (root, 600) |
/etc/xvii/platform.json |
the desired state: services, versions, settings, disabled flags, host overrides |
/etc/xvii/<service>/env |
a service's generated settings (root:xvii-<service>, 640) |
/etc/xvii/id/clients/<service>.json |
the OIDC clients id reads |
/etc/xvii/caddy.env |
the DNS token Caddy uses for DNS-01 |
/var/lib/xvii/<service>/ |
a service's data |
/var/lib/xvii/releases/<service>/<version>/ |
the release store: manifest.json, binaries, SHA256SUMS |
/usr/local/lib/xvii/<service>/<version>/ |
installed binaries; current links the running one |
/etc/systemd/system/xvii-<service>.service |
units |
/etc/caddy/conf.d/xvii.caddy |
the platform's sites |
/run/xvii/node.sock |
xvii-node's socket for home (group xvii-admin) |
PostgreSQL has one role per service named like its system user (xvii-pages), peer authentication over
the local socket, and a database xvii_<service>.
Service settings
Each service reads KEY=VALUE lines from /etc/xvii/<service>/env, and environment variables
XVII_<SERVICE>_<KEY> win over the file. xvii-node writes the file from:
- generated values:
DOMAIN, LISTEN, DATA_DIR, PUBLIC_URL, ID_URL, DATABASE_URL,
OIDC_CLIENT_ID, OIDC_SECRET (kept across updates);
- the manifest's fixed
env;
- settings set in home (the manifest's declared settings as a form, plus free
KEY=value pairs).
Change settings in home → Services → the service → Settings: saving restarts the service. Don't edit
the env file by hand; the next apply rewrites it.
Common settings
| Key |
Services |
|
SMTP_URL, MAIL_FROM |
id, notify |
outgoing mail: smtp://user:pass@host:port |
PUBLIC_URL |
all |
the service's address, when not https://<host>.<domain> |
LISTEN |
all |
the local address (set by xvii-node from the manifest's port) |
Each service's panel and spec list its own settings.
Ports
| Port |
Service |
| 8700 |
home |
| 8701 |
id |
| 8702 |
pages |
| 8703 |
notify |
| 8704 |
backups |
| 8705 |
env |
| 8706 |
apps |
| 8707 |
domains |
| 8708 |
tunnel |
| 8709 |
hooks |
| 8710 |
status |
| 8711 |
errors |
| 8712 |
analytics |
| 8713 |
ai |
| 8714 |
share |
| 8715 |
config |
| 8716 |
mail |
| 8717 |
docs |
All listen on 127.0.0.1; Caddy routes each host to its port. mail also listens on 10025, 5587, 4465, 1143
and 1993 for its mail protocols. Nodes' relay proxies listen on 7443.
Host overrides
xvii-node host SERVICE LABEL serves a service at <LABEL>.<domain> instead of its manifest's host, for
example to run a second version beside the first during a migration. xvii-node host SERVICE goes back.