Installation on Kubernetes

Before you start

This guide is for teams that already operate a Kubernetes cluster. If you have a single Linux server, the standard installation is simpler and fully supported — you do not need Kubernetes to run Collabase. You need:

	Requirement
Cluster	Kubernetes 1.26 or later
Tools	`kubectl` and Helm 3.10+ on your machine
Ingress	An ingress controller (the chart defaults to nginx)
Certificates	cert-manager with a ClusterIssuer, if you want automatic HTTPS
Storage	A default StorageClass (about 45 GB across all volumes)

By default the chart runs Collabase as a single instance with files on cluster volumes. To run multiple instances, switch file storage to an S3-compatible bucket and enable the dedicated worker — see Scaling out below.

Install

The chart ships inside the release package under deployment/helm.

Download and unpack the release

Download collabase-deployment-<version>.zip from the releases page and unpack it.

Install the chart

helm install collabase ./deployment/helm \
  --namespace collabase --create-namespace \
  --set app.url=https://collabase.yourcompany.com \
  --set ingress.host=collabase.yourcompany.com \
  --set ingress.tls.clusterIssuer=letsencrypt-prod

All passwords and keys are generated automatically on first install.

Wait for the first start

The database setup runs as a one-time job right after install. The application can answer with errors for a minute or two until it finishes. Watch it complete:

kubectl get jobs -n collabase --watch

Read your admin password

kubectl get secret collabase -n collabase \
  -o jsonpath='{.data.adminPassword}' | base64 -d

Updating

helm upgrade collabase ./deployment/helm -n collabase --reuse-values

Database migrations run automatically before the new version starts.

Never delete the collabase Secret in the namespace. It holds the key that encrypts stored credentials (for example mail and integration logins). If that key is lost, those stored credentials cannot be recovered and must be entered again. Upgrades always keep the existing keys — deleting the Secret by hand is the only way to lose them.

To get an automatic database backup before every upgrade, enable the backup option once:

helm upgrade collabase ./deployment/helm -n collabase \
  --reuse-values --set backup.enabled=true

Using your own database

If you run a managed PostgreSQL (for example Cloud SQL or RDS):

--set postgresql.enabled=false \
--set postgresql.externalUrl="postgresql://user:password@your-db-host:5432/collabase"

Collabase needs the vector extension in PostgreSQL. On managed databases you may have to enable it explicitly in your provider’s console before the first install.

Scaling out

Running more than one application instance requires two things, and the chart refuses to render without them (with a message explaining why):

S3 file storage — with cluster volumes, a second instance cannot see files the first one stored. Set up a private bucket first (File storage guide — providers, permissions, policy):

--set storage.driver=s3 \
--set storage.s3.bucket=collabase \
--set storage.s3.endpoint=https://your-s3-endpoint \
--set storage.s3.accessKeyId=... \
--set storage.s3.secretAccessKey=...

The dedicated worker — background jobs (automations, indexing) move to their own single instance so they run exactly once:
--set workers.separate=true \ --set replicaCount=3

The database connection pool is split across instances automatically.

If you migrate an existing single-instance installation to S3, copy the files into the bucket first — the File storage guide has the step-by-step migration.

Restoring a backup

Restore your database dump first, then run helm upgrade. Do not restore into a brand-new helm install — a fresh install runs its first-time setup, which would write on top of your restored data.

Troubleshooting

The install failed with a job error. Read the job’s log — it names the problem directly:

kubectl logs job/collabase-migrate -n collabase

The page shows errors right after install. Normal for the first minute or two while the setup jobs finish. Check kubectl get jobs -n collabase. I need help. Open a ticket at collabase.featurebase.app and attach the output of kubectl get pods -n collabase and the job log above.

Get Started

Core Concepts

Collabase Apps

Administration

Installation on Kubernetes

Before you start

Install

Updating

Using your own database

Scaling out

Restoring a backup

Troubleshooting

​Before you start

​Install

​Updating

​Using your own database

​Scaling out

​Restoring a backup

​Troubleshooting

Before you start

Install

Updating

Using your own database

Scaling out

Restoring a backup

Troubleshooting