This guide walks you through deploying the full Countly stack on a Kubernetes cluster using Helmfile. It covers cloning the reference environment, picking sizing, TLS, observability, and security profiles, filling in the required credentials, and applying the seven Helm charts in a single command. It is intended for DevOps engineers, SREs, and platform teams who self-host Countly on Kubernetes.

Prerequisites

Before you begin, you must have the following in place:

• A Kubernetes cluster with kubectl access and permissions to create namespaces and cluster-scoped resources.
• Helm 3 and Helmfile installed locally.

• The required Kubernetes operators installed in the cluster: cert-manager, External Secrets Operator, Strimzi Kafka Operator, ClickHouse Operator, MongoDB Kubernetes Operator, and an NGINX Ingress controller. 

• A DNS record you control, so you can point your chosen hostname at the ingress controller after deployment.
• Image pull credentials for any private registry you plan to use (e.g., Google Artifact Registry).

Copying the Reference Environment

The repository ships with an environments/reference directory that contains every value file you need, with inline documentation. Start by copying it under a new name that identifies your deployment:

cp -r environments/reference environments/my-deployment

Replace my-deployment with a stable identifier (for example, the customer name or the cluster name). You will reference this name in every command that follows.

Choosing Profiles in global.yaml

Open environments/my-deployment/global.yaml and select one value for each of the five profile dimensions. Profiles compose freely: you can mix any sizing with any TLS, observability, Kafka Connect, or security mode.

In addition to the five profiles, set the following keys in global.yaml:

• ingress.hostname — the public hostname for your Countly instance.
• global.imageSource.mode — keep the default direct for the public registry, or switch to gcpArtifactRegistry and set global.imageSource.gcpArtifactRegistry.repositoryPrefix to your GAR path.
• global.imagePullSecrets — required when pulling Countly images from a private registry.

Filling in the Required Credentials

Each chart has its own credentials file under environments/my-deployment/. Open each file and supply the values listed below.

If you would rather see every required secret in one place, refer to secrets.example.yaml in the reference environment. It lists all required keys across all charts.

Choosing a Secret Mode

Set secrets.mode in each credentials-*.yaml file to one of:

• values — direct YAML values. Suitable for evaluation or for files encrypted with SOPS.
• existingSecret — reference a Kubernetes secret you have already created out of band.
• externalSecret — have the chart create an ExternalSecret resource backed by your Secret Manager store. Set secrets.externalSecret.remoteRefs to point at the keys.

Registering the Environment in helmfile.yaml.gotmpl

Helmfile reads its environments from the top-level helmfile.yaml.gotmpl. Add a new entry that matches the directory name you chose:

environments:
  my-deployment:
    values:
      - environments/my-deployment/global.yaml

This makes my-deployment a valid value for the -e flag in the Helmfile command in the next step.

Deploying with Helmfile

Run a single Helmfile command to apply all charts in the correct order:

helmfile -e my-deployment apply

Helmfile installs MongoDB, ClickHouse, and Kafka first, then the Countly application, then the observability stack. The first apply takes several minutes because the operators must provision stateful workloads and wait for them to become healthy.

Verifying the Deployment

After helmfile apply returns, confirm the stack is healthy before pointing traffic at it.

1. Check that all pods are running across the seven namespaces:

   kubectl get pods -n countly
   kubectl get pods -n mongodb
   kubectl get pods -n clickhouse
   kubectl get pods -n kafka
   kubectl get pods -n observability

2. Confirm that the ingress has an external address:

   kubectl get ingress -n countly

3. Point a DNS record for your ingress.hostname at that address.

4. Open https://<your-hostname> in a browser. Countly should serve the first-time setup screen. 

Common Issues and Gotchas

Related Resources