Docmost

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 — UI, REST API, and collaboration websockets on port 3000 — backed by a PostgreSQL instance for documents and a bundled Redis for queues and realtime coordination, with attachments stored either on a persistent volume or in an S3 bucket.

Architecture

Docmost server — A stateful workload running the single official image, which serves the web UI, the REST API, and the Yjs collaboration websocket on port 3000. It runs its database migrations automatically on boot and scales horizontally through docmost.replicas.
PostgreSQL — The postgres template as a subchart. It holds every page, user, space, and permission.
Redis — A bundled single-node Redis with AOF persistence, deployed by this chart. It carries the background job queues, the socket.io adapter, and cross-replica collaboration sync. Docmost requires it: the server does not report healthy without a reachable Redis.
Attachment storage — Either a persistent volume mounted at /app/data/storage (default) or an S3 bucket you own.

What Gets Created

Stateful Docmost Workload — The Docmost server on port 3000 ({release}-docmost), with docmost.replicas replicas and configurable CPU and memory.
Stateful Redis Workload — The bundled single-node Redis ({release}-docmost-redis) with password authentication.
Stateful PostgreSQL Workload — One PostgreSQL instance from the subchart, with its own volume set.
Volume Sets — One for local attachments (mounted only when storage.type is local), one for the Redis AOF file, and one for the PostgreSQL data directory.
Secret — A template-created dictionary secret ({release}-docmost-creds) holding the PostgreSQL and Redis credentials used to assemble DATABASE_URL and REDIS_URL. Your prerequisite APP_SECRET secret is not created by the template — see Prerequisites.
Identity & Policy — An identity bound to the Docmost workload, and a policy granting it reveal on exactly the secrets it reads: the credentials secret, your prerequisite secret, and — when configured — the S3 key and SMTP secrets. In keyless S3 mode the identity also carries the cloud account link and your bucket-scoped IAM policy.

This template does not create a GVC. You must deploy it into an existing GVC.

Prerequisites

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

Create the APP_SECRET secret

The payload is a single random string of at least 32 characters:

printf '%s' "$(openssl rand -hex 32)" | \
  cpln secret create-opaque --name my-docmost-app-secret --encoding plain -f -

Use printf rather than echo so the payload carries no trailing newline.

Point the template at it

Set secrets.name to the secret’s name (default my-docmost-app-secret). Secrets are org-level, so no GVC flag is involved.

Back the value up

Store a copy somewhere safe, outside Control Plane.

Create the secret before installing. Installing without it succeeds, but the deployment then pauses with

The secret my-docmost-app-secret no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed.

and never becomes ready. APP_SECRET is also write-once: rotating it logs out every user and invalidates every outstanding invitation and share link. Stored documents are unaffected.

Everything else works with the defaults. Two optional features need their own setup first:

S3 attachment storage — an existing bucket plus either a Control Plane cloud account (AWS) or a static-key secret (S3-compatible servers). See Attachment Storage. Required if you plan to run more than one replica.
Authenticated SMTP — a dictionary secret holding SMTP_USERNAME and SMTP_PASSWORD. See Email.

Once your APP_SECRET secret exists, install the template using your preferred method:

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

First Run

Docmost ships no default account, and the first person to reach the instance creates the workspace and its owner account.

Wait for the workload to report ready

PostgreSQL and Redis come up first, then Docmost applies its schema migrations before it starts serving. A default install typically reaches ready in about a minute.

Open the endpoint and claim the workspace

Browse to the canonical *.cpln.app endpoint of the {release}-docmost workload and complete the setup form to create the workspace and the admin account. Do this as soon as the workload is ready.

Configure email before inviting anyone

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

Configuration

The default values.yaml for this template:

docmost:
  image: docmost/docmost:0.95.0
  replicas: 1 # >1 REQUIRES storage.type: s3; replicas coordinate via Redis
  appUrl: "" # public base URL used in links; empty = derive from the canonical endpoint
  resources:
    minCpu: 250m
    maxCpu: 1000m
    minMemory: 512Mi
    maxMemory: 2Gi # headroom for boot migrations and large imports

secrets:
  name: my-docmost-app-secret # opaque secret holding APP_SECRET — MUST exist before install

storage:
  type: local # local | s3 (s3 required for replicas > 1)
  local:
    volumeset:
      capacity: 10 # GiB (minimum 10); mounted at /app/data/storage
  s3:
    bucket: my-docmost-bucket
    region: us-east-1
    endpoint: "" # set for S3-compatible servers (e.g. http://my-minio:9000)
    forcePathStyle: false # true for most S3-compatible servers (MinIO)
    cloudAccountName: my-s3-cloud-account # keyless AWS auth; used only when auth.secretName is empty
    policyName: my-docmost-s3-policy # your pre-created bucket-scoped IAM policy
    auth:
      secretName: "" # dictionary secret with AWS_S3_ACCESS_KEY_ID + AWS_S3_SECRET_ACCESS_KEY; S3-compatible servers only
  fileUploadSizeLimit: 50mb # max single attachment size

smtp:
  enabled: false # off = member invites cannot be delivered
  host: smtp.example.com
  port: 587
  secure: false # false = STARTTLS/plain (587); true = implicit TLS (465)
  fromAddress: no-reply@example.com
  fromName: Docmost
  auth:
    secretName: "" # optional dictionary secret with SMTP_USERNAME + SMTP_PASSWORD

publicAccess:
  enabled: true # HTTPS UI + websockets on the auto *.cpln.app endpoint; false = internal-only

internalAccess:
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads: [] # used only with workload-list, e.g. //gvc/GVC_NAME/workload/WORKLOAD_NAME

postgres: # documents, users, spaces
  image: postgres:18
  config:
    username: docmost
    password: change-me-docmost-pg # change before installing
    database: docmost
  resources:
    minCpu: 250m
    maxCpu: 1000m
    minMemory: 512Mi
    maxMemory: 1Gi
  volumeset:
    capacity: 10 # initial capacity in GiB (minimum is 10)

redis: # bundled single node — queues + realtime coordination (required)
  image: redis:8
  auth:
    password: change-me-docmost-redis # change before installing
  resources:
    minCpu: 100m
    maxCpu: 400m
    minMemory: 256Mi
    maxMemory: 512Mi
  volumeset:
    capacity: 10 # GiB (minimum 10); AOF at /data

Docmost Server

image — The official Docmost image. Pin a released tag.
replicas — Number of Docmost replicas. Anything above 1 requires storage.type: s3; the chart fails the render with a clear message otherwise. See Scaling.
appUrl — The public base URL Docmost puts in invitation and share links, including the https:// scheme. Leave it empty to derive it from the workload’s canonical endpoint; set it when you serve Docmost on a custom domain.
resources — CPU and memory bounds for the Docmost container. The memory ceiling leaves headroom for the boot migrations and large imports.

Attachment Storage

storage.type decides where uploaded files, images, and avatars are kept.

Local volume (default)
AWS S3 (keyless)
S3-compatible (MinIO and others)

Attachments are written to a persistent volume set mounted at /app/data/storage, and survive restarts, redeploys, and upgrades under the same release name.

storage:
  type: local
  local:
    volumeset:
      capacity: 10 # initial capacity in GiB (minimum is 10)

Local storage works only with a single replica — each replica would get its own volume, so attachments uploaded through one replica would be missing from the others.

AWS S3 uses a Control Plane cloud identity: no credentials are stored, and the workload’s identity vends 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.

Create a bucket

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

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.

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:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::YOUR_BUCKET_NAME",
        "arn:aws:s3:::YOUR_BUCKET_NAME/*"
      ]
    }
  ]
}

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, and no access keys exist anywhere.

S3-compatible servers cannot federate with a cloud account, so they use static access keys held in a dictionary secret.

Create a bucket

Create the bucket on your server. For the MinIO template deployed in the same GVC, the S3 API address is http://WORKLOAD_NAME.GVC_NAME.cpln.local:9000.

Set the endpoint

Set storage.s3.endpoint to the S3 API address including scheme and port, and storage.s3.forcePathStyle: true (required by most S3-compatible servers).

Create the key secret

Create a dictionary secret with the server’s credentials and set storage.s3.auth.secretName to its name:

cpln secret create-dictionary --name my-docmost-s3-keys \
  --entry AWS_S3_ACCESS_KEY_ID=YOUR_ACCESS_KEY \
  --entry AWS_S3_SECRET_ACCESS_KEY=YOUR_SECRET_KEY

The Docmost identity is granted reveal on exactly this secret.

storage.fileUploadSizeLimit caps the size of a single attachment (default 50mb).

An upload larger than storage.fileUploadSizeLimit is stored truncated at the limit rather than rejected with an error — the file appears in the page but is incomplete. Raise the limit before importing large attachments.

Scaling

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.

docmost:
  replicas: 2
storage:
  type: s3
  s3:
    bucket: my-docmost-bucket
    region: us-east-1
    cloudAccountName: my-s3-cloud-account
    policyName: my-docmost-s3-policy

docmost.replicas above 1 requires storage.type: s3. Local attachments live on per-replica volumes, so an attachment uploaded through one replica would return a 404 from another. The chart refuses to render the combination.

At two replicas, a rolling upgrade served every health check without a single failure, and killing a replica outright cost one failed request before the replacement rejoined automatically.

Access

publicAccess.enabled — Serve the UI, API, and collaboration websockets on the auto-assigned *.cpln.app HTTPS endpoint (default). Set to false for an internal-only instance: external requests are then refused at the edge, and in-GVC callers still reach it per internalAccess.
internalAccess.type — Controls which workloads can reach Docmost over the internal network:

Type	Description
`none`	No internal access.
`same-gvc`	Allow access from all workloads in the same GVC (default).
`same-org`	Allow access from all workloads in the same organization.
`workload-list`	Allow access only from workloads listed in `internalAccess.workloads`.

Flipping publicAccess.enabled changes the load balancer configuration, so the public endpoint may return 503 for a minute or two after the upgrade reports success.

Email

SMTP is off by default, and a default install works without it — the first visitor still creates the workspace and the admin account, and that account signs in with its password.

smtp:
  enabled: true
  host: smtp.example.com
  port: 587
  secure: false
  fromAddress: no-reply@example.com
  fromName: Docmost
  auth:
    secretName: my-docmost-smtp # dictionary secret with SMTP_USERNAME + SMTP_PASSWORD

For an authenticated relay, create the credentials secret before installing and reference it by name:

cpln secret create-dictionary --name my-docmost-smtp \
  --entry SMTP_USERNAME=apikey --entry SMTP_PASSWORD=YOUR_PASSWORD

Leave smtp.auth.secretName empty for a relay that does not require authentication. When it is set, the Docmost identity is granted reveal on exactly that secret.

With SMTP disabled there is no way to deliver a member invitation. The image sends no mail and writes no invitation link to the workload logs, so an invitation created in the UI never reaches its recipient. Configure smtp.* for any workspace with more than one member.

Databases

postgres.config.username / password / database — Credentials for the bundled PostgreSQL from the postgres subchart. Change the password before installing — it seeds the database on first boot and is not updated by later value edits.
postgres.resources / postgres.volumeset.capacity — CPU and memory bounds and the initial data volume size in GiB (minimum 10).
redis.auth.password — Password for the bundled Redis, wired into Docmost’s REDIS_URL. Change it before installing. Redis requires authentication: an unauthenticated client is refused.
redis.resources / redis.volumeset.capacity — CPU and memory bounds and the volume size for the Redis AOF file at /data.

Redis is not optional. Docmost’s health check reports the Redis connection alongside the database one, and the workload does not become ready without it. A Redis restart briefly fails readiness on the Docmost workload, which recovers on its own without restarting the application container.

Connecting

What	Value
Public UI / API	`https://<canonical>.cpln.app` — `status.canonicalEndpoint` of `{release}-docmost` (`cpln workload get {release}-docmost -o yaml`)
Collaboration websocket	`wss://<canonical>.cpln.app/collab` — used by the editor, no separate configuration
Health check	`https://<canonical>.cpln.app/api/health` (readiness) and `/api/health/live` (liveness) — unauthenticated
Internal (same GVC)	`http://{release}-docmost.{gvc}.cpln.local:3000`
Login	The admin account created on first visit
PostgreSQL (internal)	`{release}-postgres.{gvc}.cpln.local:5432`, credentials from `postgres.config`
Redis (internal)	`{release}-docmost-redis.{gvc}.cpln.local:6379`, password from `redis.auth.password`

Important Notes

Create the APP_SECRET secret before installing — secrets.name must point at an existing opaque secret (plain encoding) whose payload is a random string of at least 32 characters. A missing secret pauses the deployment until the secret exists, and the install looks broken until then.
APP_SECRET is write-once — rotating it logs out every user and invalidates outstanding invitation and share links. Stored documents are unaffected. 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.
With SMTP off, member invitations cannot be delivered — no mail is sent and no invitation link is written to the logs. Configure smtp.* before inviting anyone.
docmost.replicas above 1 requires storage.type: s3 — local attachments are per-replica and would 404 across replicas.
AWS S3 is keyless only — use a cloud account plus a bucket-scoped IAM policy. Static keys are accepted only when storage.s3.endpoint points at an S3-compatible server.
Uploads larger than storage.fileUploadSizeLimit are truncated, not rejected — raise the limit before importing large attachments.
Change postgres.config.password and redis.auth.password before installing — both seed their component on first boot and are not updated by later value edits.
Pages survive restarts and upgrades — documents live in the PostgreSQL volume set and local attachments in the storage volume set. Uninstalling deletes those volume sets and everything in them; your APP_SECRET secret is yours and survives an uninstall.
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

File Storage

Local and S3 attachment storage options

Email Configuration

SMTP settings for invitations and notifications

Docmost on GitHub

Source code and release notes

Docmost Template

View the source files, default values, and chart definition

Template Catalog

Templates

Overview

Architecture

What Gets Created

Prerequisites

UI

CLI

Terraform

Pulumi

First Run

Configuration

Docmost Server

Attachment Storage

Scaling

Access

Email

Databases

Connecting

Important Notes

External References

Docmost Documentation

Environment Variables

File Storage

Email Configuration

Docmost on GitHub

Docmost Template

​Overview

​Architecture

​What Gets Created

​Prerequisites

UI

CLI

Terraform

Pulumi

​First Run

​Configuration

​Docmost Server

​Attachment Storage

​Scaling

​Access

​Email

​Databases

​Connecting

​Important Notes

​External References

Docmost Documentation

Environment Variables

File Storage

Email Configuration

Docmost on GitHub

Docmost Template

Overview

Architecture

What Gets Created

Prerequisites

First Run

Configuration

Docmost Server

Attachment Storage

Scaling

Access

Email

Databases

Connecting

Important Notes

External References