← All apps

BookStack

Organize documentation into books with persistent uploads and a private MariaDB database.

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

Deployment Complete local deployment with persistent dependenciesUse Selfhost with Standalone CLIDashboard

Set up BookStack

Complete local deployment with persistent dependencies

• Choose the MariaDB stack and select the first administrator email and name. A portable initialization hook replaces the upstream default account with the generated ADMIN_PASSWORD before normal use.
• The hook only initializes the default account or an instance with no administrator. It preserves existing administrator accounts on subsequent starts.

Customize deployment inputs (4)

Local HTTP port port

portDefault: 6875

Initial hostname (change public URL later in app settings) hostname

hostnameDefault: "localhost"

Administrator email admin-email

emailDefault: "admin@example.com"

Administrator display name admin-name

identifierDefault: "admin"

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

{
  "port": 6875,
  "hostname": "localhost",
  "admin-email": "admin@example.com",
  "admin-name": "admin"
}

selfhost app --directory ./bookstack init bookstack --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 ./bookstack start

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

cd bookstack
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.
• The startup hook replaces only BookStack's initial default administrator. Existing administrator accounts are not reset. Sign in with the selected email and ADMIN_PASSWORD.
• Save APP_KEY with your backup. Do not rotate it casually because it protects encrypted application data.

Before configuring integrations

• Identity connection stages OIDC discovery and client credentials. Before switching Authentication method to oidc, map the intended administrator external identity subject. Create IdP administrator can create a separate administrator with an unused email.
• BookStack replaces password login when AUTH_METHOD is changed to oidc. Keep a database backup and a way to revert this environment setting; verify the selected administrator mapping first.
• For a domain change, first back up the database, run Migrate stored content URLs with old and new URLs, and change the Public URL setting. Recreate the service.
• Maintenance actions rebuild search, permissions and content references. Keep APP_KEY and both MariaDB and application volumes in backups.
• Database placement supports MariaDB and MySQL on a private network. These mappings accept only TLS mode disable; sources requiring TLS are rejected by these bindings. Certificate-aware custom deployments remain manual. Do not send these database connections over a public network.
• OIDC setup is staged deliberately because enabling it changes the primary login method. Selfhost does not claim a verified browser login just from saving credentials.
• SMTP, OIDC groups and database fields are configurable. SAML and LDAP authentication require the corresponding additional native settings in the portable Compose environment.

BookStack integrations

Compose service: bookstack. These operations use the profile saved when this deployment is created.

Native settings

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

Supported fields (24)

Public URL public-url

string

Application name app-name

string

Timezone timezone

string

Default language locale

string

MariaDB/MySQL host database-host

string · advanced

Database port database-port

string · advanced

Database name database-name

string · advanced

Database username database-user

string · advanced

Database password database-password

secret · advanced

SMTP host mail-host

string

SMTP port mail-port

string

SMTP username mail-user

string

SMTP password mail-password

secret

Sender address mail-from

string

Authentication method auth-method

OIDC replaces local password login. Configure the administrator external ID before switching. stringChoices: standard, oidc, saml2, ldap

OIDC label oidc-name

string

OIDC client ID oidc-client

string

OIDC client secret oidc-secret

secret

OIDC issuer oidc-issuer

string

Discover OIDC endpoints oidc-discovery

stringChoices: true, false

Sync IdP groups oidc-groups

string · advancedChoices: true, false

Groups claim oidc-group-claim

string · advanced

Remove groups absent from IdP oidc-remove-groups

string · advancedChoices: true, false

Automatically redirect to IdP auto-login

string · advancedChoices: true, false

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 ./bookstack config bookstack
selfhost app --directory ./bookstack plan bookstack changes.json
selfhost app --directory ./bookstack apply bookstack 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.

Identity provider login

Selfhost can register a client with a supported provider and configure this app. Callback path: /oidc/callback.

No administrator role is assigned by Selfhost. Check the app’s first-login policy and retain a local recovery account.

Save connection.json and replace the URLs. Supply SELFHOST_IDP_TOKEN privately in your shell.

{
  "provider": "zitadel",
  "issuer": "https://identity.example.com",
  "app_url": "https://app.example.com",
  "name": "BookStack"
}

selfhost app --directory ./bookstack connect-account bookstack connection.json
selfhost app --directory ./bookstack connect-plan bookstack connection.json
selfhost app --directory ./bookstack connect bookstack connection.json --revision REVIEWED_REVISION

Test sign-in in a separate browser session. HTTPS domains and HTTP loopback development origins are supported by Selfhost; the chosen app and provider must also accept the resulting callback. Provider permissions, localhost and recovery.

Database placement

This recipe supports mariadb, mysql. 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.

• mariadb adapter TLS modes: disable. Use a private network for connections with TLS disabled.
• mysql adapter TLS modes: disable. 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

Initialize administrator

Replace only the untouched initial account, or create the first administrator when none exists. Existing administrator accounts cause a safe refusal.

Email email

stringLength: 1 to 4096 characters

Name name

stringLength: 1 to 4096 characters

Password password

secretLength: 12 to 4096 characters

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

selfhost app --directory ./bookstack action bookstack initialize-admin --inputs action-inputs.json

Create administrator

Create a separate administrator account with local credentials.

Email email

stringLength: 1 to 4096 characters

Name name

stringLength: 1 to 4096 characters

Password password

secretLength: 12 to 4096 characters

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

selfhost app --directory ./bookstack action bookstack create-admin --inputs action-inputs.json

Create IdP administrator

Create an administrator with an exact external identity subject. Use an unused email and verify it before switching AUTH_METHOD.

Email email

stringLength: 1 to 4096 characters

Name name

stringLength: 1 to 4096 characters

External identity subject subject

stringLength: 1 to 4096 characters

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

selfhost app --directory ./bookstack action bookstack create-external-admin --inputs action-inputs.json

Migrate stored content URLs

Replace old public URLs in stored content. Back up the database first and separately update APP_URL.

Old URL old-url

stringLength: 1 to 4096 characters

New URL new-url

stringLength: 1 to 4096 characters

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

selfhost app --directory ./bookstack action bookstack update-url --inputs action-inputs.json

Rebuild search index · schedulable

Regenerate the application search index.

selfhost app --directory ./bookstack action bookstack rebuild-search

A workspace can schedule this workflow while Selfhost runs. A standalone user can invoke it through an external scheduler. Scheduling guide.

Rebuild access permissions

Recalculate content permissions from current roles.

selfhost app --directory ./bookstack action bookstack rebuild-permissions

Rebuild reference index

Regenerate the cross-content reference index.

selfhost app --directory ./bookstack action bookstack rebuild-references

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: mariadb:11.4.8
• bookstack: lscr.io/linuxserver/bookstack:version-v26.09

• 26.09 lscr.io/linuxserver/bookstack:version-v26.09

  Local MariaDB stack replaced default administrator through native initialization, verified selected password, rebuilt search and retained data across recreation. OIDC credentials are staged; enabling login needs verified account mapping.

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 · BookStack documentation