selfhost
← All apps

Wiki.js

Write and organize a collaborative wiki with a private PostgreSQL database.

Choose your deployment and the way you want to use Selfhost. The instructions below follow that choice.

Set up Wiki.js

Complete local deployment with persistent dependencies

  • Choose the PostgreSQL stack and start it. Run Initial setup with an administrator email, password and the public site URL. The setup action only runs while the native first-run wizard is present.
  • The portable deployment includes a small native GraphQL helper in files/wiki-manage.cjs. Keep that file when moving the Compose directory.
Customize deployment inputs (2)
Local HTTP port port
portDefault: 3005
Initial hostname (change public URL later in app settings) hostname
hostnameDefault: "localhost"

Save this as inputs.json and adjust the values before initialization. 

{
  "port": 3005,
  "hostname": "localhost"
}
selfhost app --directory ./wiki-js init wiki-js --method stack --inputs inputs.json

Initialization writes portable files and does not start the app. Review compose.yaml, the private .env and any files in files/, then start it: 

selfhost app --directory ./wiki-js start

No Selfhost dashboard or background service is needed. You can also start these files directly: 

cd wiki-js
docker compose -f compose.yaml up -d
  • Review the generated Compose and environment before starting. Only the app HTTP port is published, on loopback.
  • Keep credentials, database and data volumes together in an independent backup. Exported Compose files do not include volume data.
  • Use App setup to select the first administrator and site URL; telemetry is disabled by the setup profile.
  • Configure content storage destinations and additional identity providers in Wiki.js administration.

Before configuring integrations

  • List identity providers signs in using a local administrator and returns provider summaries plus a revision. Supply that revision to Add OpenID Connect provider with a new provider ID and the existing client endpoints and credentials.
  • The identity action preserves existing providers and local login. New providers have self-registration and automatic group enrollment disabled. Add existing user mappings in Wiki.js administration.
  • Native database settings and the version action are available from the same dashboard and CLI integration interface.
  • Database placement supports PostgreSQL, MySQL and MariaDB. Wiki.js verifies server certificates whenever database TLS is enabled; add the database CA certificate body when using a private certificate authority.
  • The identity action requires a local administrator without a pending MFA or password challenge. Accounts requiring those challenges should use Wiki.js administration.
  • Do not edit authentication strategies concurrently in Wiki.js while applying a reviewed identity action. The upstream API replaces the strategy collection and does not provide atomic compare-and-swap.
  • This profile configures an existing OIDC client; it does not create the client at the identity provider. Storage targets, mail delivery and other Wiki.js modules are configured in its administration interface.

Wiki.js integrations

Compose service: wiki-js. These operations use the profile saved when this deployment is created.

Initialize and connect

Supported setup modes: bootstrap.

  • Initializes a new wiki and its first administrator. Telemetry is disabled. Existing installations are never reset.
Setup fields
Administrator email email
string · requiredLength: 1 to 255 characters
Administrator password password
secret · requiredLength: 12 to 255 characters
Public site URL site-url
string · requiredLength: 1 to 255 characters

Save onboarding.json, replace example values and supply env: secrets privately through your shell. Empty apps adds no links; add explicit links when this profile supports them. 

{
  "mode": "bootstrap",
  "inputs": {
    "email": "YOUR_VALUE",
    "password": "env:SELFHOST_PASSWORD",
    "site-url": "YOUR_VALUE"
  },
  "apps": []
}
selfhost app --directory ./wiki-js setup wiki-js
selfhost app --directory ./wiki-js setup-plan wiki-js onboarding.json
selfhost app --directory ./wiki-js setup-apply wiki-js onboarding.json --revision REVIEWED_REVISION

Setup modes, secret references and recovery

Native settings

Changes use the app’s Compose environment. Unrelated settings are preserved.

Supported fields (10)
Database type database-type
string · advancedChoices: postgres, mysql, mariadb, mssql, sqlite
Database host database-host
string · advanced
Database port database-port
string · advanced
Database username database-user
string · advanced
Database password database-password
secret · advanced
Database name database-name
string · advanced
Database TLS database-tls
string · advancedChoices: true, false
High availability mode high-availability
string · advancedChoices: true, false
Database CA certificate body database-ca
Base64 certificate body without PEM delimiters. Wiki.js verifies the database certificate when TLS is enabled. string · advanced
Log level log-level
string · advancedChoices: error, warn, info, verbose, debug

Save a JSON map of the field IDs you want to change as changes.json. Replace FIELD_ID with an ID from the supported fields above, and use its declared value type. Review the plan and replace REVIEWED_REVISION with the revision it returns. 

{
  "FIELD_ID": "YOUR_VALUE"
}
selfhost app --directory ./wiki-js config wiki-js
selfhost app --directory ./wiki-js plan wiki-js changes.json
selfhost app --directory ./wiki-js apply wiki-js changes.json --revision REVIEWED_REVISION

Saved changes need service recreation to become active. Existing interpolated environment values stay under your control in .env or Compose.

Database placement

This recipe supports postgres, mysql, mariadb. Workspace projects can choose a dedicated database, a shared source with a separate database and account, or an existing external database before their first start.

  • postgres adapter TLS modes: disable, require, verify-full. Use a private network for connections with TLS disabled.
  • mysql adapter TLS modes: disable, require, verify-full. Use a private network for connections with TLS disabled.
  • mariadb adapter TLS modes: disable, require, verify-full. Use a private network for connections with TLS disabled.

Standalone directories use the generated Compose and environment files directly. Configure the database there before first start. Selfhost’s source provisioning commands belong to workspace projects and are optional.

Database setup, CLI commands and backups

App actions

Show version

Read the installed Wiki.js package version.

selfhost app --directory ./wiki-js action wiki-js version
Inspect identity providers

List configured providers and produce a revision for adding a provider. No secrets are returned.

Local administrator email admin-email
stringLength: 1 to 4096 characters
Local administrator password admin-password
secretLength: 12 to 4096 characters

Save the input IDs and selected values in a private action-inputs.json file. 

selfhost app --directory ./wiki-js action wiki-js list-identities --inputs action-inputs.json
Connect an existing OIDC client

Add a new provider while preserving current providers and local login. First inspect providers and supply that revision. New-user registration and group-based administrator grants stay disabled. Do not edit authentication simultaneously in Wiki.js.

Local administrator email admin-email
stringLength: 1 to 4096 characters
Local administrator password admin-password
secretLength: 12 to 4096 characters
Reviewed provider revision revision
stringLength: 1 to 4096 characters
New provider ID provider
stringLength: 1 to 4096 characters
Login label label
stringLength: 1 to 4096 characters
Issuer URL issuer
stringLength: 1 to 4096 characters
Authorization endpoint authorization-url
stringLength: 1 to 4096 characters
Token endpoint token-url
stringLength: 1 to 4096 characters
User information endpoint userinfo-url
stringLength: 1 to 4096 characters
Client ID client-id
stringLength: 1 to 4096 characters
Client secret client-secret
secretLength: 12 to 4096 characters

Save the input IDs and selected values in a private action-inputs.json file. 

selfhost app --directory ./wiki-js action wiki-js connect-oidc --inputs action-inputs.json

App configuration reference

Versions and updates

This deployment uses the following images. Existing projects retain their saved recipe and images. A new catalogue version does not silently update them.

  • database: postgres:17-alpine
  • wiki-js: ghcr.io/requarks/wiki:2.5.315
  • 2.5.315 ghcr.io/requarks/wiki:2.5.315

    Local PostgreSQL initialization through native setup API, selected administrator login, reviewed OIDC strategy addition preserving local login, environment changes and persistent recreation passed. External provider login was not performed.

Review compatibility and back up app data before an update. Choose an image version and review the change.

Keep control of your setup

Selfhost remains optional. Your app runs using ordinary Compose files, its own settings and persistent data. Keep the Compose project name and volumes to preserve storage. Configuration exports and setting backups do not include application data.

Standalone CLI guide · Backups and removal · Wiki.js documentation

Built by Obiente. Your services, your configuration.

Licensed under AGPL-3.0-or-later.