Skip to main content
Run Collabase in a Kubernetes cluster with the Helm chart that ships in the release package. This guide takes you from an empty namespace to a running installation, and then covers the choices a cluster operator makes: certificates, your own image registry, an external database, scaling and backups. If you have a single Linux server, the installation with Docker is simpler and fully supported. You do not need Kubernetes to run Collabase.

At a glance

Requirements

The full list of ports, outbound connections and images is on System requirements. Send that page to the team that runs your cluster.

What runs in your cluster

The chart creates six workloads, each with one instance, and two one-time jobs. The memory the scheduler reserves is 512 MB for the app, 1 GB for the database and 256 MB for the sandbox. The chart also sets small CPU requests: 250m for the app, 100m each for the document processor, the sandbox and the collaboration relay. The database and the queue set none. If your namespace has a resource quota or a limit range that demands more, set them in your values file, see Adjust resources.
With the default settings the app and its volumes run as a single instance. To run more than one instance, see Scale out.

Install

Phase 1 of 3. Next: Verify the installation.
1

Unpack the release package

Download collabase-deployment-<version>.zip from the download page and unpack it. The chart is in deployment/helm.
2

Write a values file

Keep your settings in a file, not in a long command. Create collabase-values.yaml:
collabase-values.yaml
app.url is the public address people open. It must match ingress.host.
3

Install the chart

The chart installs the images of the release it belongs to. All passwords and keys are generated on the first install.
4

Wait for the first start

The database is prepared by a one-time job. The application can answer with errors until it finishes.
5

Read the administrator password

Sign in at your address with the administrator email from your values file and this password. You are asked to choose a new password.
Create the first admin yourself. The chart starts a first-run job that creates an admin from secrets.adminPassword. Set migrations.seed: false to skip it: the installation then starts without an admin and the first visit to /setup creates the admin, the title and the language. The default is true.

Verify the installation

Phase 2 of 3. Previous: Install. Next: Activate the licence and add people.
Checkpoint. All pods are Running and ready, both jobs are Complete, and the address answers with "status":"ok".
If something is not ready, see Troubleshooting.

Certificates

The ingress terminates HTTPS. Choose one way to get a certificate.
Use your own certificate
Create the secret before the install so the ingress finds it at the start.

Use another ingress controller

The chart sets nginx annotations and defaults to the class nginx. For another controller, set ingress.className and check these three points:
  • Upload size. Allow request bodies of at least 32 MB. The chart sets the nginx annotation proxy-body-size from ingress.maxBodySize. Other controllers need the same limit in their own way, through ingress.annotations.
  • WebSockets. Live collaboration connects to /collab on the same address. The controller must pass WebSocket upgrades through.
  • Sign-in rate limit. The chart adds a second ingress that limits sign-in attempts with an nginx annotation. Set ingress.authRateLimit.enabled: false for a controller that ignores it, and limit /api/auth/callback in your own gateway.
The Docker installation also limits all other requests per client address. The chart does not. Set a general request limit in your gateway or ingress if you need one. To manage the routes yourself, set ingress.enabled: false. Route / to the service collabase-app on port 3000, and /collab to the service collabase-collab on port 1234. The service names start with your release name.

Use your own image registry

Many clusters cannot pull from ghcr.io. Copy the images into your registry, then point the chart at them.
1

Copy the images

Copy these images at the version of your release package. The tag is the version number without a leading v.
2

Set the repositories

collabase-values.yaml
The tags stay empty. Each image uses the version of the chart.
3

Allow the cluster to pull

If your registry needs a login, create a pull secret in the namespace and list it in imagePullSecrets in your values file, for example imagePullSecrets: [{ name: ghcr-pull }]. The chart sets it on every pod.
A cluster with no route to the internet at all can also use the air-gapped installation approach for the images.

Use your own database

Use a managed PostgreSQL by turning off the bundled one:
collabase-values.yaml
The database must be PostgreSQL 16 or later with the vector extension. The migration job runs CREATE EXTENSION IF NOT EXISTS vector, which needs a privileged user. If your provider restricts it, enable the extension once in the provider’s console. See System requirements. The connection pool is sized for you. Each app process gets 80 % of max_connections divided by the number of processes, at most 100 each. Override it with database.connectionLimit.

Manage secrets

On the first install the chart generates every password and key and stores them in the secret collabase. Later upgrades keep the existing values.
Never delete the secret collabase. It holds the key that encrypts stored credentials such as mail and integration logins. If it is lost, those credentials cannot be recovered and must be entered again. helm uninstall removes the secret too. Include it in your backup.
Tools that render the chart without a live connection to the cluster, such as helm template in a GitOps pipeline, cannot read the existing secret. They would generate new keys on every render. In that case create the secret yourself and reference it:
collabase-values.yaml
The secret needs these keys: postgresPassword, nextauthSecret, adminPassword, pdfPrintToken, automationEncryptionKey, encryptionKey, mailEncryptionKey, databaseUrl, collabSharedSecret, sandboxSharedSecret and engineTokenSecret. With S3 storage add s3AccessKeyId and s3SecretAccessKey. Generate each value as a random string of at least 32 characters. If you move an existing Docker installation to Kubernetes, copy ENCRYPTION_KEY, MAIL_ENCRYPTION_KEY, AUTOMATION_ENCRYPTION_KEY, NEXTAUTH_SECRET, PDF_PRINT_TOKEN and POSTGRES_PASSWORD from the .env file into the secrets section of your values file on the first install.

Adjust resources

Every workload takes its limits from the values file. Raise them in the same place:
collabase-values.yaml
The same resources block exists for documentProcessor, collab, sandbox and postgresql. These are the CPU requests the chart sets by default: Without a CPU request Kubernetes would reserve the whole limit as the request, so these small values let the scheduler place the pods without holding cores they do not use. To size the whole installation for your team, see Sizing & scaling. The database settings under postgresql.tuning assume a node with at least 8 GB of RAM. Lower shared_buffers and effective_cache_size on a smaller one.

Plug sandbox

The sandbox runs automation plugs from third parties in isolation. It starts with every install. It needs a security profile on the node to isolate plugs fully. Without the profile it still starts, reports degraded on its health check and runs no third-party plug. Everything else works as before. Localhost for AppArmor needs Kubernetes 1.30 or later. Network policies keep the sandbox away from the database and the queue. Your cluster must enforce them.

Scale out

Running more than one app instance needs two things. The chart refuses to render without them.
  1. S3 file storage. With cluster volumes, a second instance cannot see files the first one stored. Set up a private bucket first, see File storage.
  2. A dedicated worker. Background jobs move to their own single instance so they run exactly once.
collabase-values.yaml
With S3 storage the app pods carry no volumes and update without downtime. For the database and the other parts, see Sizing & scaling.

Roll out without downtime

These values change how the app instances update and stop. Every default keeps your installation as it is. Instances get 40 seconds to finish open requests when they stop, workers 60 seconds. With more than one instance the chart also creates a disruption budget, so draining a node never takes all instances away at once. With Redis, the request limit counts across all instances.

Pod security

Many platforms enforce the Kubernetes Pod Security Standards on a namespace, or run a policy engine such as Kyverno or OPA Gatekeeper. The chart was checked against a server-side dry run in a namespace that enforces restricted. With securityContext.enabled: true (off by default) the chart runs every workload except the sandbox as a non-root user with the ID of its image, without privilege escalation, with all capabilities dropped and the default seccomp profile. The root filesystem stays writable. Override single keys under podSecurityContext and containerSecurityContext of a workload if a platform assigns user IDs itself or an image or volume does not work with these values (app, collab, documentProcessor, redis, postgresql, migrations, backup). Volumes of the database and the queue are set up for the image users with fsGroup; on a new Kubernetes version with an old storage driver that ignores it, make the volume writable for the user ID 999. A policy engine may also require resource requests and limits, images from approved registries or pinned versions. The chart pins every image to the release by default and sets memory requests, but sets CPU requests only if you add them, see Adjust resources.

Network connections

The chart ships one network policy, for the plug sandbox. If your cluster denies traffic by default, allow these connections. All ports are TCP. The app pods and the worker pod need the same connections. The sandbox may reach the internet except private address ranges, and DNS. Add your pod network to sandbox.networkPolicy.internetExceptCidrs if it is not in a private range.

Scheduling and platform settings

The chart has settings for nodeSelector, imagePullSecrets and app.spreadAcrossNodes. It has none for tolerations, affinity, priority class, pod annotations or extra environment variables. Use these ways instead:
  • Pull secrets: set imagePullSecrets, see Use your own image registry.
  • Scheduling and annotations: let Helm pass the rendered manifests to a post-renderer such as Kustomize with helm install --post-renderer. The post-renderer adds the fields you need to the pods.
  • Node pools: if your platform assigns nodes per namespace, set it on the namespace.

Monitoring

Collabase has no metrics endpoint for Prometheus. Monitor it with probes, cluster metrics and the health address. Alert on pods that restart or stay unready, on failed jobs, on volumes that fill up, on a certificate close to expiry and on degraded in the health response. See Health check.

Availability

With the default settings every part runs once. A restart of the app, the database or the queue interrupts the service for the time the pod needs to start, and nothing fails over to another copy.

Update

Unpack the new release package and upgrade with the same values file:
The chart installs the version it belongs to, so the new package moves every image to the new release. Migrations run before the new version starts. The full procedure, with backup, checks and rollback, is on Updates.

Back up and restore

Back up three things: the database, the uploaded files and the secret collabase. The chart can also take a database dump before each upgrade:
collabase-values.yaml
The dump goes to its own volume and the last seven days are kept. Turn the option on one upgrade before the one you want protected, because the volume is created after the checks of that first upgrade. This does not replace your regular backup. See Backup & Restore. If your storage supports volume snapshots, snapshot the volumes for uploads, documents and the shared home directory. A snapshot of the running database is only crash-consistent. For the database, rely on a dump. With S3 storage, turn on versioning in the bucket. Test a restore on your test system before you need it. Restore a database dump into the existing installation, then run helm upgrade. Do not restore into a new helm install. A fresh install runs its first-time setup and would write on top of your restored data.

Remove Collabase

This removes the workloads, the secret and the volumes for uploads, documents and the sandbox. The volumes of the database and the queue are kept. Back up the secret and your data first. Delete the remaining volumes with kubectl delete pvc only when you want the data gone for good. This cannot be undone.

Kubernetes versions

The chart is written for Kubernetes 1.26 or later. A list of the versions we tested against each release is not published yet. Ask us for the current state before you plan. Helm 3.10 or later is required. A newer minor version of Kubernetes needs no change to the chart as long as the APIs it uses stay available: apps/v1, batch/v1 and networking.k8s.io/v1.

OpenShift and other distributions

Managed Kubernetes services and hybrid platforms built on upstream Kubernetes need nothing beyond the requirements. The chart has not been tested on OpenShift. These are the points that differ there. Tell us if you use it, and we verify the installation with you.

Troubleshooting

Collect kubectl get pods -n collabase and the log of the failing pod or job before you contact support at collabase.featurebase.app.

Next steps

Phase 3 of 3. Previous: Verify the installation.

Activate your licence

Unlock the Enterprise features.

First run

Invite your team and create a Space.

Updates

Plan how you keep Collabase current.
Last modified on November 13, 2026