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 port3000) 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.
What Gets Created
APP_SECRET secret is not created by the template — see Prerequisites.
Prerequisites
Docmost signs sessions, invitation links, and share links with anAPP_SECRET that you supply through an opaque secret created before installing. The value never passes through Helm values.
Create the APP_SECRET secret
printf rather than echo so the payload carries no trailing newline:secrets.name to this name. Secrets are org-level, so no GVC flag is involved.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.- 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_USERNAMEandSMTP_PASSWORD. See Email. - Scheduled database backups — a bucket and cloud account for the bundled PostgreSQL. See Backing Up.
Installation
Once yourAPP_SECRET secret exists, install from the marketplace registry, pointing secrets.name at it and replacing both bundled-component passwords:
postgres.config.credentialsSecretName to a name no other release uses — secret names are org-wide.
Other ways to install and manage the template:
UI
CLI
Terraform
Pulumi
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.
smtp.auth.secretName to its name. The Docmost identity is granted reveal on exactly that secret.
Access
Bundled PostgreSQL
The database is the postgres template as a subchart, so every knob of that template is available underpostgres.*. 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.Connecting
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.Wait for the Docmost workload to report ready
Open the endpoint and claim the workspace
Configure email before inviting anyone
Operations
Attachment Storage on S3
Setstorage.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 (keyless)
- S3-compatible (MinIO and others)
storage.s3.endpoint is set.Create a bucket
storage.s3.bucket and storage.s3.region to match.Set up a cloud account
storage.s3.cloudAccountName to its name.Create a bucket-scoped IAM policy
YOUR_BUCKET_NAME with your bucket), then set storage.s3.policyName to the policy’s name:Leave the key secret empty
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. Enablingpostgres.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.
- AWS S3
- Google Cloud Storage
- MinIO / S3-compatible
Create a bucket
postgres.backup.aws.bucket and postgres.backup.aws.region to match.Set up a cloud account
postgres.backup.aws.cloudAccountName to its name.Create a bucket-scoped IAM policy
YOUR_BUCKET_NAME) and set postgres.backup.aws.policyName to its name: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-SQLpg_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:
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.
Upgrading from 1.0.0
Version 1.1.0 adopted thepostgres 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:
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.
Troubleshooting
Deployment never becomes ready and the logs are empty
Deployment never becomes ready and the logs are empty
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.Second install refused as managed by a different release
Second install refused as managed by a different release
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.Render fails because replicas above 1 require s3 storage
Render fails because replicas above 1 require s3 storage
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.Render fails because static keys are only for S3-compatible servers
Render fails because static keys are only for S3-compatible servers
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.Upgrade from 1.0.0 fails asking you to create a dictionary secret
Upgrade from 1.0.0 fails asking you to create a dictionary secret
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.Member invitations never arrive
Member invitations never arrive
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.Uploaded attachment is incomplete
Uploaded attachment is incomplete
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_SECRETsecret before installing —secrets.namemust 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_SECRETas 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.replicasabove1requiresstorage.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.fileUploadSizeLimitare truncated, not rejected — raise the limit before importing large attachments. - Change
postgres.credentials.passwordandredis.auth.passwordbefore 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_SECRETsecret is yours and survives. - Docmost is licensed under the AGPL — this template deploys the open-source edition.