Skip to content
Countly icon
v1.3.2App: v25.05.4Pinned DigestS3 Backup Ready

Production Helm chart • Apache-2.0 • Zero-Root • Verified on Kubernetes v1.33-v1.36+

Countly Helm Chart

Deploy Countly product analytics on Kubernetes with the official countly/countly-server:25.05.4 image, a bundled or external MongoDB, optional Gateway API and External Secrets integration, and scheduled S3-compatible backups.

Features

  • Separate, configurable Countly API and dashboard listeners.
  • HelmForge MongoDB dependency or one external MongoDB URI.
  • Ingress and Gateway API exposure for the dashboard.
  • External Secrets support for MongoDB credentials.
  • Default NetworkPolicy and disabled service-account token mounting.
  • Optional non-root MongoDB-to-S3 backup pipeline.
  • Runtime validation of both application listeners, including custom ports.

Architecture

One pod runs the official combined Countly image with independent API and dashboard processes. Named Service targets keep Kubernetes ports separate from the native listener values. MongoDB is the only durable state; the application tier and backup staging directory are disposable.

Installation

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install countly helmforge/countly

OCI installation:

helm install countly oci://ghcr.io/helmforgedev/helm/countly

Access the dashboard without public exposure:

kubectl port-forward service/countly-countly 8080:80

Open http://127.0.0.1:8080 and complete the Countly setup flow.

Configuration

The most important values are:

Value Default Purpose
countly.apiPort 3001 Native SDK ingestion listener.
countly.dashboardPort 6001 Native dashboard listener.
service.apiPort 3001 Kubernetes Service port for ingestion.
service.port 80 Kubernetes Service port for the dashboard.
mongodb.enabled true Deploy HelmForge MongoDB.
externalMongodb.enabled false Use an external MongoDB URI.
networkPolicy.enabled true Create the Countly NetworkPolicy.
backup.enabled false Schedule MongoDB backups to object storage.

See configuration for the full operating contract.

External MongoDB

Prefer an existing Secret so the URI does not enter Helm release values:

mongodb:
  enabled: false

externalMongodb:
  enabled: true
  existingSecret: countly-mongodb
  existingSecretUriKey: mongodb-uri

The Secret value must contain a complete MongoDB URI, including any authSource, replica-set, TLS, and certificate parameters required by the managed service.

Backups

backup:
  enabled: true
  s3:
    endpoint: https://s3.example.com
    bucket: countly-backups
    existingSecret: countly-backup-s3

Backups stage one compressed archive in ephemeral storage before upload. Read backup and restore before enabling the schedule.

Security

The chart disables Kubernetes API token mounting, applies seccomp, creates a NetworkPolicy, and runs init and backup containers as non-root. The official combined Countly image must start its supervisor as root before it drops the Node.js processes to the countly user; this documented upstream constraint is why the main container does not set runAsNonRoot.

Restrict networkPolicy.ingressFrom and networkPolicy.egress, keep database and object-store credentials in Secrets, expose both listeners only through TLS, and scan the pinned image in your admission pipeline. See security.

Production Guidance

  • Use a managed or replicated MongoDB topology with tested backups.
  • Set resource requests and limits from observed load.
  • Keep the dashboard private where possible; SDK clients need only the API.
  • Use External Secrets or pre-created Secrets for credentials.
  • Test custom plugin requirements and outbound policy before restricting egress.
  • Perform a restore drill before relying on scheduled backups.

A reusable baseline is available in the production example.

Examples

Operations and Troubleshooting

The operations guide covers upgrades, probes, listener verification, scaling limits, and common failures. The external MongoDB example and simple example are renderable values files.

Limitations

  • MongoDB is the only supported datastore.
  • The pinned combined upstream image is amd64-only.
  • The chart does not claim application or database high availability.
  • Ingress and HTTPRoute target the dashboard; expose the API separately when SDKs are outside the cluster.

More Information

Security Scan: countly

Framework Score
MITRE + NSA + SOC2 72.72727%

Security posture acceptable.

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
    SDK[Countly SDK clients] --> API[Service API port]
    User[Dashboard users] --> Web[Ingress or HTTPRoute]
    Web --> Dashboard[Service dashboard port]
    API --> Pod[Countly API and dashboard pod]
    Dashboard --> Pod
    Pod --> Mongo[(Bundled or external MongoDB)]
    Backup[Backup CronJob] --> Mongo
    Backup --> S3[(S3-compatible storage)]
Official Contractvalues.schema.json

Countly Values Schema Reference

Official schema parameters, default values, and types extracted directly from the chart repository.

116 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Global values accepted by Helm dependencies.

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring-Chart configuration parameter

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring-Chart configuration parameter

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsobject-Chart configuration parameter

Image(3)

ParameterTypeDefaultDescription
image.repositorystring-Chart configuration parameter
image.tagstring-Chart configuration parameter
image.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Chart configuration parameter

Countly(6)

ParameterTypeDefaultDescription
countly.apiPortinteger-Chart configuration parameter
countly.dashboardPortinteger-Chart configuration parameter
countly.apiWorkersinteger-Chart configuration parameter
countly.timezonestring-Chart configuration parameter
countly.pluginsstring-Chart configuration parameter
countly.extraEnvarray-Chart configuration parameter

External Mongodb(4)

ParameterTypeDefaultDescription
externalMongodb.enabledboolean-Chart configuration parameter
externalMongodb.uristring-Chart configuration parameter
externalMongodb.existingSecretstring-Chart configuration parameter
externalMongodb.existingSecretUriKeystring-Chart configuration parameter

Service Account(4)

ParameterTypeDefaultDescription
serviceAccount.createboolean-Chart configuration parameter
serviceAccount.namestring-Chart configuration parameter
serviceAccount.annotationsobject-Chart configuration parameter
serviceAccount.automountServiceAccountTokenboolean-Chart configuration parameter

Service & Networking(6)

ParameterTypeDefaultDescription
service.typestring-Chart configuration parameter
Allowed:ClusterIPNodePortLoadBalancer
service.portinteger-Chart configuration parameter
service.apiPortinteger-Chart configuration parameter
service.annotationsobject-Chart configuration parameter
service.ipFamilyPolicystring-Chart configuration parameter
Allowed:SingleStackPreferDualStackRequireDualStack
service.ipFamiliesarray-Chart configuration parameter

Ingress(5)

ParameterTypeDefaultDescription
ingress.enabledboolean-Chart configuration parameter
ingress.ingressClassNamestring-Chart configuration parameter
ingress.annotationsobject-Chart configuration parameter
ingress.hostsarray-Chart configuration parameter
ingress.tlsarray-Chart configuration parameter

Health Probes(15)

ParameterTypeDefaultDescription
probes.startup.enabledboolean-Chart configuration parameter
probes.startup.initialDelaySecondsinteger-Chart configuration parameter
probes.startup.periodSecondsinteger-Chart configuration parameter
probes.startup.timeoutSecondsinteger-Chart configuration parameter
probes.startup.failureThresholdinteger-Chart configuration parameter
probes.liveness.enabledboolean-Chart configuration parameter
probes.liveness.initialDelaySecondsinteger-Chart configuration parameter
probes.liveness.periodSecondsinteger-Chart configuration parameter
probes.liveness.timeoutSecondsinteger-Chart configuration parameter
probes.liveness.failureThresholdinteger-Chart configuration parameter
probes.readiness.enabledboolean-Chart configuration parameter
probes.readiness.initialDelaySecondsinteger-Chart configuration parameter
probes.readiness.periodSecondsinteger-Chart configuration parameter
probes.readiness.timeoutSecondsinteger-Chart configuration parameter
probes.readiness.failureThresholdinteger-Chart configuration parameter

Resources(1)

ParameterTypeDefaultDescription
resourcesobject-Chart configuration parameter

Pod Security(1)

ParameterTypeDefaultDescription
podSecurityContext.seccompProfile.typestring-Chart configuration parameter

Container Security(4)

ParameterTypeDefaultDescription
securityContext.allowPrivilegeEscalationboolean-Chart configuration parameter
securityContext.readOnlyRootFilesystemboolean-Chart configuration parameter
securityContext.runAsNonRootboolean-Chart configuration parameter
securityContext.runAsUserinteger-Chart configuration parameter

Network Policy(3)

ParameterTypeDefaultDescription
networkPolicy.enabledboolean-Chart configuration parameter
networkPolicy.ingressFromarray-Chart configuration parameter
networkPolicy.egressarray-Chart configuration parameter

Backup(33)

ParameterTypeDefaultDescription
backup.enabledboolean-Chart configuration parameter
backup.schedulestring-Chart configuration parameter
backup.suspendboolean-Chart configuration parameter
backup.concurrencyPolicystring-Chart configuration parameter
Allowed:AllowForbidReplace
backup.successfulJobsHistoryLimitinteger-Chart configuration parameter
backup.failedJobsHistoryLimitinteger-Chart configuration parameter
backup.backoffLimitinteger-Chart configuration parameter
backup.archivePrefixstring-Chart configuration parameter
backup.images.mongodbstring-Chart configuration parameter
backup.images.uploaderstring-Chart configuration parameter
backup.resourcesobject-Chart configuration parameter
backup.podSecurityContext.fsGroupinteger-Chart configuration parameter
backup.podSecurityContext.fsGroupChangePolicystring-Chart configuration parameter
backup.podSecurityContext.seccompProfile.typestring-Chart configuration parameter
backup.securityContext.allowPrivilegeEscalationboolean-Chart configuration parameter
backup.securityContext.capabilities.droparray-Chart configuration parameter
backup.securityContext.readOnlyRootFilesystemboolean-Chart configuration parameter
backup.securityContext.runAsNonRootboolean-Chart configuration parameter
backup.securityContext.runAsUserinteger-Chart configuration parameter
backup.securityContext.runAsGroupinteger-Chart configuration parameter
backup.s3.endpointstring-Chart configuration parameter
backup.s3.bucketstring-Chart configuration parameter
backup.s3.prefixstring-Chart configuration parameter
backup.s3.createBucketIfNotExistsboolean-Chart configuration parameter
backup.s3.existingSecretstring-Chart configuration parameter
backup.s3.existingSecretAccessKeyKeystring-Chart configuration parameter
backup.s3.existingSecretSecretKeyKeystring-Chart configuration parameter
backup.s3.accessKeystring-Chart configuration parameter
backup.s3.secretKeystring-Chart configuration parameter
backup.database.uristring-Chart configuration parameter
backup.database.existingSecretstring-Chart configuration parameter
backup.database.existingSecretUriKeystring-Chart configuration parameter
backup.database.mongodumpArgsany-Extra mongodump arguments. Arrays are preferred; legacy space-delimited strings remain accepted for upgrade compatibility.

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Chart configuration parameter

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Chart configuration parameter

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Chart configuration parameter

Topology Spread Constraints(1)

ParameterTypeDefaultDescription
topologySpreadConstraintsarray-Chart configuration parameter

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring-Chart configuration parameter

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger-Chart configuration parameter

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsobject-Chart configuration parameter

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Chart configuration parameter

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Chart configuration parameter

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Chart configuration parameter

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Chart configuration parameter

Mongodb(5)

ParameterTypeDefaultDescription
mongodb.enabledboolean-Chart configuration parameter
mongodb.architecturestring-Chart configuration parameter
Allowed:standalonereplicaset
mongodb.auth.enabledboolean-Chart configuration parameter
mongodb.auth.rootUserstring-Chart configuration parameter
mongodb.auth.rootPasswordstring-Chart configuration parameter

Gateway(3)

ParameterTypeDefaultDescription
gateway.enabledboolean-Chart configuration parameter
gateway.hostnamesarray-Chart configuration parameter
gateway.parentRefsarray-Chart configuration parameter

External Secrets(7)

ParameterTypeDefaultDescription
externalSecrets.enabledboolean-Chart configuration parameter
externalSecrets.apiVersionstring-Chart configuration parameter
Allowed:external-secrets.io/v1external-secrets.io/v1beta1
externalSecrets.refreshIntervalstring-Chart configuration parameter
externalSecrets.secretStoreRef.namestring-Chart configuration parameter
externalSecrets.secretStoreRef.kindstring-Chart configuration parameter
Allowed:SecretStoreClusterSecretStore
externalSecrets.target.creationPolicystring-Chart configuration parameter
Allowed:OwnerOrphanMergeNone
externalSecrets.dataarray-Chart configuration parameter