Skip to main content

Overview

Docmost is an open-source knowledge base and wiki — a Confluence or Notion alternative with real-time collaborative editing, spaces, and per-space permissions. This template deploys the Docmost server (web UI, REST API, and collaboration websocket on port 3000) backed by a bundled PostgreSQL for documents and a bundled Redis for job queues and realtime coordination, with attachments kept on a persistent volume or in an S3 bucket you own. The default is a single replica; docmost.replicas scales out once attachments live in S3.
This template deploys into an existing GVC that you already have — it does not create or manage a GVC.

What Gets Created

Your APP_SECRET secret is not created by the template — see Prerequisites.

Prerequisites

Docmost signs sessions, invitation links, and share links with an APP_SECRET that you supply through an opaque secret created before installing. The value never passes through Helm values.
1

Create the APP_SECRET secret

The payload is a single random string of at least 32 characters. Use printf rather than echo so the payload carries no trailing newline:
Set secrets.name to this name. Secrets are org-level, so no GVC flag is involved.
2

Back the value up outside Control Plane

APP_SECRET is effectively write-once: rotating it logs out every user and invalidates every outstanding invitation and share link (stored documents are unaffected). Keep a copy somewhere safe.
Create the secret before installing. Installing without it reports success, but the deployment then wedges silently — cpln logs returns nothing, and the only place the missing secret is named is status.versions[].message:
The message reads The secret APP_SECRET_NAME no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed. Creating the secret lets the deployment recover on its own; cpln workload force-redeployment RELEASE_NAME-docmost --gvc GVC_NAME skips the wait.
Everything else works with the defaults. Three optional features need their own setup first:
  • S3 attachment storage (required for more than one replica) — an existing bucket plus either an AWS cloud account and bucket-scoped IAM policy, or a static-key secret for an S3-compatible server. See Attachment Storage on S3.
  • Authenticated SMTP — a dictionary secret holding SMTP_USERNAME and SMTP_PASSWORD. See Email.
  • Scheduled database backups — a bucket and cloud account for the bundled PostgreSQL. See Backing Up.

Installation

Once your APP_SECRET secret exists, install from the marketplace registry, pointing secrets.name at it and replacing both bundled-component passwords:
Installing a second Docmost release in the same org? Also set postgres.config.credentialsSecretName to a name no other release uses — secret names are org-wide. Other ways to install and manage the template:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

Docmost Server

Prerequisite Secret

Attachment Storage

storage.type decides where uploaded files, images, and avatars are kept. The default local volume works for a single replica; the bucket, cloud account, and secret setup for s3 is under Attachment Storage on S3.

Email

SMTP is off by default and a default install works without it — the first visitor still creates the workspace and signs in with a password. Member invitations, however, are delivered only by email.
For an authenticated relay, create the credentials secret before installing and set smtp.auth.secretName to its name. The Docmost identity is granted reveal on exactly that secret.

Access

A change to either access knob takes a couple of minutes to take effect after the upgrade reports success.

Bundled PostgreSQL

The database is the postgres template as a subchart, so every knob of that template is available under postgres.*. The chart builds the credentials secret from postgres.credentials.* for you — nothing to create before installing.

Bundled Redis

Redis is required: Docmost’s readiness check pings it alongside the database, and the workload does not become ready without it.
Both bundled passwords seed their component on first boot and are not updated by later value edits. Uninstalling the release deletes the volume sets; reinstall to reset.

Connecting

With publicAccess.enabled: false there is no public endpoint; reach the UI from your machine through a tunnel instead and open http://localhost:3000:

First Run

Docmost ships no default account: the first person to reach the instance creates the workspace and its owner account, and that form is open to anyone who can reach the endpoint.
1

Wait for the Docmost workload to report ready

PostgreSQL and Redis come up first, then Docmost applies its schema migrations and starts serving.
2

Open the endpoint and claim the workspace

Browse to the canonical endpoint (or the port-forward URL) and complete the setup form to create the workspace and the owner account. Do this as soon as the workload is ready.
3

Configure email before inviting anyone

Member invitations are delivered only by email. Configure SMTP before you invite your team.

Operations

Attachment Storage on S3

Set storage.type: s3 to keep attachments in a bucket you own. This is required for more than one replica, and nothing in the template moves existing attachments between the local volume and the bucket — choose the storage type before uploading content.
AWS S3 uses a Control Plane cloud account: no access keys are stored anywhere, and the Docmost identity obtains temporary credentials at runtime. This is the only supported way to reach AWS S3 — the chart rejects static keys unless storage.s3.endpoint is set.
1

Create a bucket

Create an S3 bucket. Set storage.s3.bucket and storage.s3.region to match.
2

Set up a cloud account

If you do not have one, create a cloud account for your AWS account. Set storage.s3.cloudAccountName to its name.
3

Create a bucket-scoped IAM policy

Create an AWS IAM policy with the JSON below (replace YOUR_BUCKET_NAME with your bucket), then set storage.s3.policyName to the policy’s name:
4

Leave the key secret empty

Keep storage.s3.auth.secretName empty. The template then attaches the cloud account and your policy to the Docmost identity.

Backing Up

Scheduled backups of the bundled PostgreSQL are off by default. Enabling postgres.backup.enabled: true adds one cron workload, RELEASE_NAME-postgres-backup, that runs pg_dumpall on the schedule and uploads a gzipped dump to your bucket under the configured prefix. Pick a postgres.backup.provider and complete the matching setup before installing or upgrading with it on.
1

Create a bucket

Create an S3 bucket. Set postgres.backup.aws.bucket and postgres.backup.aws.region to match.
2

Set up a cloud account

If you do not have one, create a cloud account for the AWS account holding the bucket. Set postgres.backup.aws.cloudAccountName to its name.
3

Create a bucket-scoped IAM policy

Create an IAM policy with the JSON below (replace YOUR_BUCKET_NAME) and set postgres.backup.aws.policyName to its name:
A zero-length backup object is a failed run, not a backup. If the dump cannot reach the database, the upload still writes a near-empty gzip under a normal timestamped filename. Check the object size before you rely on one.
Two things the database dump does not cover: local attachments live on the RELEASE_NAME-docmost-storage volume set (S3 attachments are already in your bucket), and your APP_SECRET lives in the secret you created. The PostgreSQL volume set RELEASE_NAME-pg-vs takes no scheduled snapshots; a final snapshot is taken when the volume set is deleted and kept 7 days.

Restoring a Backup

Each backup is a gzipped plain-SQL pg_dumpall archive. Restoring means replaying that SQL into the bundled PostgreSQL. The one transport that carries a dump into the container intact is cpln workload exec with --stdin and a base64 wrapper on both ends — raw binary piped through exec is corrupted:
Two constraints make this a planned operation: the archive contains CREATE ROLE and CREATE DATABASE statements, so a straight replay collides with the database Docmost already created and migrated on first boot; and no Docmost replica may be connected while you drop and recreate that database before the replay.
This restore path has not been exercised against this template end to end. Rehearse it on a throwaway release before you depend on it. Restoring from a volume set snapshot is likewise unverified here.

Upgrading from 1.0.0

Version 1.1.0 adopted the postgres 3.4.1 template, which stopped taking database credentials as values. Docmost absorbed that change rather than passing it on — the chart now creates the credentials secret itself — so there is no new prerequisite, only a rename of three keys: Move the three keys, keep the same values so the running database still matches, and upgrade in place. A values file that still carries an old key fails the render with the postgres template’s message, which tells you to create a dictionary secret yourself — ignore that advice here; this template creates it.
The first helm upgrade after an install can restart the bundled PostgreSQL even when its values are unchanged, so expect a brief interruption.

Scaling and Availability

docmost.replicas sets how many Docmost replicas run. Replicas coordinate through the bundled Redis, which carries both the job queues and the collaborative-editing updates, so a document edited on one replica appears live for a reader connected to another, and no sticky sessions are needed.
docmost.replicas above 1 requires storage.type: s3. Local attachments live on per-replica volumes, so a file uploaded through one replica would return a 404 from another. The chart refuses to render the combination.
The bundled PostgreSQL and Redis are single-instance by design: Docmost has no Sentinel support, so the highly-available Redis template is not used. Their data lives on persistent volume sets and survives restarts, redeploys, and upgrades under the same release name.

Troubleshooting

Symptom: cpln helm install reported success, cpln logs returns nothing, and cpln workload get-deployments RELEASE_NAME-docmost --gvc GVC_NAME -o yaml shows The secret APP_SECRET_NAME no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed. under status.versions[].message.Cause: The APP_SECRET prerequisite secret named by secrets.name does not exist.Fix: Create it (see Prerequisites). The deployment recovers on its own once the secret exists; cpln workload force-redeployment RELEASE_NAME-docmost --gvc GVC_NAME skips the wait.
Symptom: Installing a second Docmost release fails with cannot be updated because it is being managed by a different release and creates nothing.Cause: Both releases use the same postgres.config.credentialsSecretName. Secret names are org-wide, and the first release owns that one. Nothing is shared, overwritten, or deleted.Fix: Set postgres.config.credentialsSecretName to a distinct name for the second release and install again.
Symptom: docmost: docmost.replicas > 1 requires storage.type: s3 — local attachments live on per-replica volumesets and would scatter/404 across replicas.Cause: docmost.replicas is above 1 while storage.type is local.Fix: Complete Attachment Storage on S3 and set storage.type: s3, or keep a single replica.
Symptom: docmost: static keys (storage.s3.auth.secretName) are only for S3-compatible servers (storage.s3.endpoint set).Cause: storage.s3.auth.secretName is set without a storage.s3.endpoint. AWS S3 is keyless-only in this template.Fix: For AWS, clear storage.s3.auth.secretName and set storage.s3.cloudAccountName and storage.s3.policyName. For an S3-compatible server, set storage.s3.endpoint too.
Symptom: The render fails with the postgres template’s message about config.credentialsSecretName and a prerequisite dictionary secret.Cause: Your values file still carries postgres.config.username, postgres.config.password, or postgres.config.database.Fix: Rename them to postgres.credentials.* as described in Upgrading from 1.0.0. Do not create a secret yourself — this template creates it.
Symptom: An invitation created in the UI reaches no one, and the workload logs contain no invitation link.Cause: smtp.enabled is false. The production image sends no mail and writes no fallback link to the logs.Fix: Configure Email with smtp.enabled: true (and smtp.auth.secretName for an authenticated relay), then re-send the invitation.
Symptom: A large upload succeeds with no error but the stored file is cut off.Cause: The file exceeded storage.fileUploadSizeLimit. Docmost stores the upload truncated at the limit instead of rejecting it.Fix: Raise storage.fileUploadSizeLimit (for example 200mb) and upload the file again.

Important Notes

  • Create the APP_SECRET secret before installing — secrets.name must name an existing opaque secret (plain encoding) with a random payload of at least 32 characters. A missing secret wedges the deployment silently.
  • Treat APP_SECRET as write-once — rotating it logs out every user and invalidates outstanding invitation and share links. Back the value up outside Control Plane.
  • Claim the workspace right after install — the first visitor to complete the setup form becomes the workspace owner, and the form is reachable by anyone who can reach the endpoint.
  • With SMTP off, member invitations cannot be delivered — configure smtp.* before inviting anyone.
  • docmost.replicas above 1 requires storage.type: s3 — local attachments are per-replica.
  • AWS S3 is keyless only — a cloud account plus a bucket-scoped IAM policy; static keys are accepted only with an S3-compatible storage.s3.endpoint.
  • Uploads larger than storage.fileUploadSizeLimit are truncated, not rejected — raise the limit before importing large attachments.
  • Change postgres.credentials.password and redis.auth.password before installing — both seed their component on first boot and are not updated by later value edits.
  • Give each release its own postgres.config.credentialsSecretName — secret names are org-wide, and a second release on the same name is refused at install.
  • Uninstalling deletes the volume sets and every page and local attachment in them; your APP_SECRET secret is yours and survives.
  • Docmost is licensed under the AGPL — this template deploys the open-source edition.

External References

Docmost Documentation

Official Docmost documentation

Environment Variables

Every setting the Docmost server reads from its environment

Self-Hosting Configuration

File storage and email configuration options

Docmost on GitHub

Source code and release notes

Docmost Template

View the source files, default values, and chart definition