Coming soon. The Wiki is in active development, so features and these docs may still change. Early adopters: contact us for access.

Plan an installation

Components, requirements, sizing, network and storage to decide before installing the Wiki

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

PartRoleNotes
ServerEvery API request, live editing sessions, scheduled jobs (imports, analytics, scheduled publishing), events, pluginsPort 8080. Stateless apart from a small per-server data folder. Several servers form a cluster
Web appThe pages people use; forwards /api to the serverPort 3002 by default. Stateless; run two or more for availability
PostgreSQLEvery record: people, settings (encrypted), spaces, pages and their versions, comments, Q&A, calendars, analytics, the audit logRequired. The single source of truth
RedisCoordination between servers: rate limits, live updatesOptional on one server, required for a cluster. See Single server & cluster
File storageImages and videos on pages, imports while they run, logos, avatars and plugin packagesLocal disk, S3 (or S3-compatible), MinIO or Azure Blob
Reverse proxyTLS, the public address, /api/ws to the serverAny proxy or load balancer; examples for Caddy and nginx in Install the Wiki

2. Single server or cluster

Single serverCluster
LicenceStandard or higherPro or higher, with enough servers
RedisOptionalRequired (one server, Sentinel or Redis Cluster)
StorageAnyShared by every server: S3, MinIO, Azure, or one volume mounted at the same path everywhere
AvailabilityDowntime for restarts and upgradesRolling 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

FromToPortWhy
PeopleReverse proxy443The web app and the API, on one host name
Calendar appsReverse proxy443Calendar feeds, without signing in
Reverse proxyWeb app3002Everything except /api/ws
Reverse proxyServer8080/api/ws: live editing and alerts (WebSocket)
Web appServer8080API traffic
ServerPostgreSQL, Redis, storage5432, 6379, 443/9000Its records, coordination and files
ServersEach othernoneServers 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.