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
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
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 If something is not ready, see Troubleshooting.
Running and ready, both jobs are Complete, and the address answers with "status":"ok".Certificates
The ingress terminates HTTPS. Choose one way to get a certificate.Use your own certificate
Use another ingress controller
The chart sets nginx annotations and defaults to the classnginx. 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-sizefromingress.maxBodySize. Other controllers need the same limit in their own way, throughingress.annotations. - WebSockets. Live collaboration connects to
/collabon 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: falsefor a controller that ignores it, and limit/api/auth/callbackin your own gateway.
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 fromghcr.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
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.Use your own database
Use a managed PostgreSQL by turning off the bundled one:collabase-values.yaml
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 secretcollabase. Later upgrades keep the existing values.
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
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
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, reportsdegraded 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.- 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.
- A dedicated worker. Background jobs move to their own single instance so they run exactly once.
collabase-values.yaml
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 enforcesrestricted.
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 fornodeSelector, 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:Back up and restore
Back up three things: the database, the uploaded files and the secretcollabase. The chart can also take a database dump before each upgrade:
collabase-values.yaml
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
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.