forked from
tranquil.farm/tranquil-pds
Our Personal Data Server from scratch!
removing gen config altogether, agree with nel
-154
-154
docs/general-configuration.md
-154
docs/general-configuration.md
···
1
-
# Tranquil PDS Configuration Reference
2
-
3
-
Every option in `example.toml` is overridable by an environment variable. This document focuses on what each setting *does* and why some of them are critical to get right before you start. The install guides (`install-containers.md`, `install-kubernetes.md`, `install-nix.md`) cover the mechanics of standing up the service; this covers what to put in it.
4
-
5
-
## Configuration methods
6
-
7
-
The server accepts config in two forms, applied in this order (later wins):
8
-
9
-
1. A TOML file, defaulting to `/etc/tranquil-pds/config.toml`. Override the path with `TRANQUIL_PDS_CONFIG`.
10
-
2. Environment variables. Every TOML key has a corresponding env var documented in `example.toml`.
11
-
12
-
In practice: TOML for static, non-sensitive settings; env vars (injected from secrets) for anything that would be unfortunate in a file you may want to commit.
13
-
14
-
---
15
-
16
-
## Required settings
17
-
18
-
These have no defaults and the Tranqil will not start without them.
19
-
20
-
### `PDS_HOSTNAME`
21
-
22
-
The public hostname of your PDS. Example: `pds.example.com`.
23
-
24
-
This is used in DID documents, OAuth metadata, and the `/.well-known/atproto-did` endpoint. Getting it wrong after you have accounts is painful: DIDs are registered against this hostname in the PLC directory, and changing it requires a PLC rotation operation. Set it correctly before creating any accounts.
25
-
26
-
If your PDS hostname is also the apex domain (e.g. `example.com` rather than `pds.example.com`), users can have their handle *be* the apex domain (e.g. `@example.com`) since the PDS serves `/.well-known/atproto-did` directly without needing a DNS TXT record.
27
-
28
-
### `DATABASE_URL`
29
-
30
-
PostgreSQL connection string. Example: `postgres://tranquil_pds:password@host:5432/pds`
31
-
32
-
Tranquil PDS uses Postgres for all persistent state: accounts, repos, sessions, the comms queue, and (when using the default `postgres` repo backend) the full block store for every account's atproto repository.
33
-
34
-
---
35
-
36
-
## Required secret/sensitive env vars
37
-
38
-
These three are the most sensitive values in the entire deployment. They should never appear in a committed file, in any circumstance.
39
-
40
-
### `JWT_SECRET`
41
-
42
-
Used to sign and verify all session JWTs issued by the PDS.
43
-
44
-
Generate: `openssl rand -base64 48`
45
-
46
-
### `DPOP_SECRET`
47
-
48
-
Used to validate DPoP (Demonstrating Proof of Possession) proofs in OAuth flows. DPoP is the binding mechanism that ties an OAuth access token to the client's key pair, preventing token theft from replaying the token with a different client.
49
-
50
-
Generate: `openssl rand -base64 48`
51
-
52
-
### `MASTER_KEY`
53
-
54
-
Used as input to HKDF key derivation and for encrypting per-account signing keys at rest. Every account's atproto repo signing key is derived from or wrapped with this value.
55
-
56
-
Generate: `openssl rand -base64 48`
57
-
58
-
---
59
-
60
-
## Handle domains
61
-
62
-
### `PDS_USER_HANDLE_DOMAINS`
63
-
64
-
Comma-separated list of domains under which handles are issued. Defaults to `PDS_HOSTNAME` if unset.
65
-
66
-
If your PDS hostname is `pds.example.com` but you want handles like `alice.example.com`, set this to `example.com`. You need a wildcard TLS cert and DNS wildcard record for the domain(s) you list here.
67
-
68
-
### `PDS_BANNED_WORDS`
69
-
70
-
Comma-separated list of substring patterns blocked at registration time. Useful to prevent handles that would collide with your infrastructure (e.g. `grafana`, `vault`, `relay`). The server has a built-in exact-match reserved list (`admin`, `api`, `git`, `mail`, `ssh`, etc.); this adds substring matches for anything missing from that list.
71
-
72
-
### `INVITE_CODE_REQUIRED`
73
-
74
-
Default `true`. Keep this enabled on any public-facing PDS unless you specifically want open registration. Invite codes are generated via the admin API/UI.
75
-
76
-
---
77
-
78
-
## Blob storage
79
-
80
-
### `BLOB_STORAGE_BACKEND`
81
-
82
-
`filesystem` (default) or `s3`. Pretty straight forward, and dependent on your personal infrastructure requirements and availability.
83
-
84
-
### `BLOB_STORAGE_PATH`
85
-
86
-
Path on disk for the filesystem backend. Default `/var/lib/tranquil-pds/blobs`.
87
-
88
-
For S3: set `S3_BUCKET` and optionally `S3_ENDPOINT` for S3-compatible stores (Tigris, Cloudflare R2, MinIO, etc.).
89
-
90
-
---
91
-
92
-
## Federation
93
-
94
-
### `CRAWLERS`
95
-
96
-
Comma-separated list of relay URLs to notify when new events are committed to an account's repo. Often `https://bsky.network` for production, this is what allows your PDS to be federated to on the wider network.
97
-
98
-
---
99
-
100
-
## Email
101
-
102
-
Email is sorta optional but required for account verification, password resets, and 2FA backup codes. If `MAIL_FROM_ADDRESS` is not set, email sending is disabled entirely.
103
-
104
-
Tranquil supports two delivery modes:
105
-
106
-
### Smarthost (SMTP relay)
107
-
108
-
Set `MAIL_SMARTHOST_HOST`, `MAIL_SMARTHOST_PORT`, `MAIL_SMARTHOST_USERNAME`, and `MAIL_SMARTHOST_PASSWORD`. Use this if you're routing through a sending service (Postmark, SES, etc.) or a local MTA.
109
-
110
-
TLS mode defaults to `starttls`. Setting `tls = "none"` alongside a password is rejected at startup.
111
-
112
-
### DKIM signing (`email.dkim`)
113
-
114
-
Set `MAIL_DKIM_SELECTOR`, `MAIL_DKIM_DOMAIN`, and `MAIL_DKIM_KEY_PATH` to sign outgoing mail. The key file should be PEM-format RSA or Ed25519. The corresponding DNS TXT record at `<selector>._domainkey.<domain>` must be published before mail is sent.
115
-
116
-
---
117
-
118
-
## Notifications
119
-
120
-
Beyond email, Tranquil supports Discord, Telegram, and Signal for user notifications. Each is opt-in:
121
-
122
-
- **Discord**: Set `DISCORD_BOT_TOKEN`.
123
-
- **Telegram**: Set `TELEGRAM_BOT_TOKEN` and `TELEGRAM_WEBHOOK_SECRET`.
124
-
- **Signal**: Set `SIGNAL_ENABLED=true` after linking a device via the admin API. State is persisted in `signal_*` tables in Postgres.
125
-
126
-
---
127
-
128
-
## SSO
129
-
130
-
OAuth SSO is supported for GitHub, Discord, Google, GitLab, generic OIDC, and Apple. Each provider requires `enabled = true`, a `client_id`, and a `client_secret`. GitLab and OIDC also need an `issuer` URL.
131
-
132
-
`client_secret` values should be injected as env vars (`SSO_GITHUB_CLIENT_SECRET`, etc.) and not placed in config files.
133
-
134
-
---
135
-
136
-
## Cache backend
137
-
138
-
### `CACHE_BACKEND`
139
-
140
-
`ripple` (default) or `valkey`. Ripple is the a built-in in-process gossip cache. Valkey is an external Redis fork with it's own complications.
141
-
142
-
---
143
-
144
-
## Optional keys worth knowing
145
-
146
-
| Env var | Default | Notes |
147
-
|---|---|---|
148
-
| `PLC_ROTATION_KEY` | — | Operator-level PLC rotation key (DID key). If unset, per-user keys are used. |
149
-
| `ENABLE_PDS_HOSTED_DID_WEB` | `false` | Opt-in did:web hosting. Long-term commitment — only enable if you intend to serve DID documents indefinitely. |
150
-
| `MAX_BLOB_SIZE` | 10 GiB | Per-blob upload limit in bytes. |
151
-
| `DISABLE_RATE_LIMITING` | `false` | Only for testing. Avoid in production. |
152
-
| `DATABASE_MAX_CONNECTIONS` | 100 | Connection pool ceiling. Tune against your Postgres `max_connections`. |
153
-
| `FIREHOSE_BACKFILL_HOURS` | 72 | How many hours of history relays can replay from cursor. |
154
-
| `REPO_BACKEND` | `postgres` | `tranquil-store` is the experimental embedded backend. Careful if attempting to run in production. |