The Wiki is two programs, the server (the API, live editing, background jobs) and the web app, in front of PostgreSQL, optional Redis and file storage. Decide these before installing: they're the parts that are hard to change later.
1. Components
| Part | Role | Notes |
|---|---|---|
| Server | Every API request, live editing sessions, scheduled jobs (imports, analytics, scheduled publishing), events, plugins | Port 8080. Stateless apart from a small per-server data folder. Several servers form a cluster |
| Web app | The pages people use; forwards /api to the server | Port 3002 by default. Stateless; run two or more for availability |
| PostgreSQL | Every record: people, settings (encrypted), spaces, pages and their versions, comments, Q&A, calendars, analytics, the audit log | Required. The single source of truth |
| Redis | Coordination between servers: rate limits, live updates | Optional on one server, required for a cluster. See Single server & cluster |
| File storage | Images and videos on pages, imports while they run, logos, avatars and plugin packages | Local disk, S3 (or S3-compatible), MinIO or Azure Blob |
| Reverse proxy | TLS, the public address, /api/ws to the server | Any proxy or load balancer; examples for Caddy and nginx in Install the Wiki |
2. Single server or cluster
| Single server | Cluster | |
|---|---|---|
| Licence | Standard or higher | Pro or higher, with enough servers |
| Redis | Optional | Required (one server, Sentinel or Redis Cluster) |
| Storage | Any | Shared by every server: S3, MinIO, Azure, or one volume mounted at the same path everywhere |
| Availability | Downtime for restarts and upgrades | Rolling upgrades; a failed server's work is taken over |
Every feature behaves the same either way, live editing included: two people on different servers edit the same page together. Start with one server if you're unsure: going to a cluster later means adding Redis and shared storage, not reinstalling.
3. PostgreSQL
- A supported PostgreSQL release, 15 or later. Managed services (Amazon RDS and Aurora PostgreSQL, Google Cloud SQL, Azure Database for PostgreSQL) work.
- One database for the Wiki, owned by the role the Wiki connects as. The role needs CREATEROLE if plugins use databases, and must not be a superuser.
- Connections: each server opens up to pool_max_conns (default 4, or the number of CPUs if more). Keep servers × pool_max_conns plus room for maintenance under max_connections.
- Page views are kept month by month; on a busy installation the database grows with readers (see Analytics for what is kept and for how long).
- Use TLS (sslmode=verify-full) when the database isn't on the same host, and back it up with your platform's tools as well as with the Wiki's backups.
- The Wiki's backups run pg_dump and pg_restore on the server: install the PostgreSQL client tools on each server host, at least as new as the database server.
4. Storage
- Size it for the images and videos people put on pages: images are up to 20 MiB each, videos up to 200 MiB. An import keeps its upload in storage until it ends (2 GiB per export by default).
- Object storage (S3, MinIO, Azure) is the usual choice and the only one that needs nothing extra for a cluster. On AWS the server can use its IAM role instead of keys.
- Each server also has a small data folder of its own: the encrypted bootstrap file and its log files. Give it persistent disk.
5. Network
| From | To | Port | Why |
|---|---|---|---|
| People | Reverse proxy | 443 | The web app and the API, on one host name |
| Calendar apps | Reverse proxy | 443 | Calendar feeds, without signing in |
| Reverse proxy | Web app | 3002 | Everything except /api/ws |
| Reverse proxy | Server | 8080 | /api/ws: live editing and alerts (WebSocket) |
| Web app | Server | 8080 | API traffic |
| Server | PostgreSQL, Redis, storage | 5432, 6379, 443/9000 | Its records, coordination and files |
| Servers | Each other | none | Servers coordinate through PostgreSQL and Redis only |
Outbound from the server, only for what you use: identity providers (single sign-on, Entra ID, Google), SMTP or Amazon SES, webhook targets and plugins' declared hosts. Videos embedded from YouTube, Vimeo or the sites you allow are played by the reader's browser, not fetched by the server.
6. Address and TLS
- Give the Wiki its own host name (https://wiki.example.com); it can't be served under a path.
- Terminate TLS at your proxy. Single sign-on and calendar apps need HTTPS in practice.
- Set FRONTEND_BEHIND_PROXY=true on the web app and TRUSTED_PROXIES on the server, or every request seems to come from the proxy.
- Allow request bodies of at least 201 MiB at the proxy, so videos up to 200 MiB can be uploaded (see Install the Wiki).
7. Before you install
- PostgreSQL database and role created; Redis ready if you run a cluster; bucket or container created.
- DNS name and TLS certificate.
- A place to keep secrets: CONFIG_ENCRYPTION_KEY, the first administrator's password, the setup and recovery keys.
- Who will request the licence, and with which tier, user and server counts (see Licensing).
- Email (SMTP or Amazon SES) for invitations and password resets.
- Your identity source: local accounts, LDAP or Active Directory, Entra ID, Google Workspace, SCIM, and single sign-on.
- Whether anything will be public: public spaces and questions need anonymous access.