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 SyncedVerified 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)]Countly Values Schema Reference
Official schema parameters, default values, and types extracted directly from the chart repository.
Global(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| global | object | - | Global values accepted by Helm dependencies. |
Name Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nameOverride | string | - | Chart configuration parameter |
Fullname Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| fullnameOverride | string | - | Chart configuration parameter |
Common Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonLabels | object | - | Chart configuration parameter |
Image(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| image.repository | string | - | Chart configuration parameter |
| image.tag | string | - | Chart configuration parameter |
| image.pullPolicy | string | - | Chart configuration parameter Allowed: AlwaysIfNotPresentNever |
Image Pull Secrets(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| imagePullSecrets | array | - | Chart configuration parameter |
Countly(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| countly.apiPort | integer | - | Chart configuration parameter |
| countly.dashboardPort | integer | - | Chart configuration parameter |
| countly.apiWorkers | integer | - | Chart configuration parameter |
| countly.timezone | string | - | Chart configuration parameter |
| countly.plugins | string | - | Chart configuration parameter |
| countly.extraEnv | array | - | Chart configuration parameter |
External Mongodb(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| externalMongodb.enabled | boolean | - | Chart configuration parameter |
| externalMongodb.uri | string | - | Chart configuration parameter |
| externalMongodb.existingSecret | string | - | Chart configuration parameter |
| externalMongodb.existingSecretUriKey | string | - | Chart configuration parameter |
Service Account(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| serviceAccount.create | boolean | - | Chart configuration parameter |
| serviceAccount.name | string | - | Chart configuration parameter |
| serviceAccount.annotations | object | - | Chart configuration parameter |
| serviceAccount.automountServiceAccountToken | boolean | - | Chart configuration parameter |
Service & Networking(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| service.type | string | - | Chart configuration parameter Allowed: ClusterIPNodePortLoadBalancer |
| service.port | integer | - | Chart configuration parameter |
| service.apiPort | integer | - | Chart configuration parameter |
| service.annotations | object | - | Chart configuration parameter |
| service.ipFamilyPolicy | string | - | Chart configuration parameter Allowed: SingleStackPreferDualStackRequireDualStack |
| service.ipFamilies | array | - | Chart configuration parameter |
Ingress(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| ingress.enabled | boolean | - | Chart configuration parameter |
| ingress.ingressClassName | string | - | Chart configuration parameter |
| ingress.annotations | object | - | Chart configuration parameter |
| ingress.hosts | array | - | Chart configuration parameter |
| ingress.tls | array | - | Chart configuration parameter |
Health Probes(15)
| Parameter | Type | Default | Description |
|---|---|---|---|
| probes.startup.enabled | boolean | - | Chart configuration parameter |
| probes.startup.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.startup.periodSeconds | integer | - | Chart configuration parameter |
| probes.startup.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.startup.failureThreshold | integer | - | Chart configuration parameter |
| probes.liveness.enabled | boolean | - | Chart configuration parameter |
| probes.liveness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.liveness.periodSeconds | integer | - | Chart configuration parameter |
| probes.liveness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.liveness.failureThreshold | integer | - | Chart configuration parameter |
| probes.readiness.enabled | boolean | - | Chart configuration parameter |
| probes.readiness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.readiness.periodSeconds | integer | - | Chart configuration parameter |
| probes.readiness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.readiness.failureThreshold | integer | - | Chart configuration parameter |
Resources(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| resources | object | - | Chart configuration parameter |
Pod Security(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podSecurityContext.seccompProfile.type | string | - | Chart configuration parameter |
Container Security(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| securityContext.allowPrivilegeEscalation | boolean | - | Chart configuration parameter |
| securityContext.readOnlyRootFilesystem | boolean | - | Chart configuration parameter |
| securityContext.runAsNonRoot | boolean | - | Chart configuration parameter |
| securityContext.runAsUser | integer | - | Chart configuration parameter |
Network Policy(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| networkPolicy.enabled | boolean | - | Chart configuration parameter |
| networkPolicy.ingressFrom | array | - | Chart configuration parameter |
| networkPolicy.egress | array | - | Chart configuration parameter |
Backup(33)
| Parameter | Type | Default | Description |
|---|---|---|---|
| backup.enabled | boolean | - | Chart configuration parameter |
| backup.schedule | string | - | Chart configuration parameter |
| backup.suspend | boolean | - | Chart configuration parameter |
| backup.concurrencyPolicy | string | - | Chart configuration parameter Allowed: AllowForbidReplace |
| backup.successfulJobsHistoryLimit | integer | - | Chart configuration parameter |
| backup.failedJobsHistoryLimit | integer | - | Chart configuration parameter |
| backup.backoffLimit | integer | - | Chart configuration parameter |
| backup.archivePrefix | string | - | Chart configuration parameter |
| backup.images.mongodb | string | - | Chart configuration parameter |
| backup.images.uploader | string | - | Chart configuration parameter |
| backup.resources | object | - | Chart configuration parameter |
| backup.podSecurityContext.fsGroup | integer | - | Chart configuration parameter |
| backup.podSecurityContext.fsGroupChangePolicy | string | - | Chart configuration parameter |
| backup.podSecurityContext.seccompProfile.type | string | - | Chart configuration parameter |
| backup.securityContext.allowPrivilegeEscalation | boolean | - | Chart configuration parameter |
| backup.securityContext.capabilities.drop | array | - | Chart configuration parameter |
| backup.securityContext.readOnlyRootFilesystem | boolean | - | Chart configuration parameter |
| backup.securityContext.runAsNonRoot | boolean | - | Chart configuration parameter |
| backup.securityContext.runAsUser | integer | - | Chart configuration parameter |
| backup.securityContext.runAsGroup | integer | - | Chart configuration parameter |
| backup.s3.endpoint | string | - | Chart configuration parameter |
| backup.s3.bucket | string | - | Chart configuration parameter |
| backup.s3.prefix | string | - | Chart configuration parameter |
| backup.s3.createBucketIfNotExists | boolean | - | Chart configuration parameter |
| backup.s3.existingSecret | string | - | Chart configuration parameter |
| backup.s3.existingSecretAccessKeyKey | string | - | Chart configuration parameter |
| backup.s3.existingSecretSecretKeyKey | string | - | Chart configuration parameter |
| backup.s3.accessKey | string | - | Chart configuration parameter |
| backup.s3.secretKey | string | - | Chart configuration parameter |
| backup.database.uri | string | - | Chart configuration parameter |
| backup.database.existingSecret | string | - | Chart configuration parameter |
| backup.database.existingSecretUriKey | string | - | Chart configuration parameter |
| backup.database.mongodumpArgs | any | - | Extra mongodump arguments. Arrays are preferred; legacy space-delimited strings remain accepted for upgrade compatibility. |
Node Selector(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nodeSelector | object | - | Chart configuration parameter |
Tolerations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| tolerations | array | - | Chart configuration parameter |
Affinity(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| affinity | object | - | Chart configuration parameter |
Topology Spread Constraints(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| topologySpreadConstraints | array | - | Chart configuration parameter |
Priority Class Name(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| priorityClassName | string | - | Chart configuration parameter |
Termination Grace Period Seconds(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| terminationGracePeriodSeconds | integer | - | Chart configuration parameter |
Pod Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podLabels | object | - | Chart configuration parameter |
Pod Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podAnnotations | object | - | Chart configuration parameter |
Extra Volumes(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumes | array | - | Chart configuration parameter |
Extra Volume Mounts(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumeMounts | array | - | Chart configuration parameter |
Extra Manifests(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraManifests | array | - | Chart configuration parameter |
Mongodb(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| mongodb.enabled | boolean | - | Chart configuration parameter |
| mongodb.architecture | string | - | Chart configuration parameter Allowed: standalonereplicaset |
| mongodb.auth.enabled | boolean | - | Chart configuration parameter |
| mongodb.auth.rootUser | string | - | Chart configuration parameter |
| mongodb.auth.rootPassword | string | - | Chart configuration parameter |
Gateway(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| gateway.enabled | boolean | - | Chart configuration parameter |
| gateway.hostnames | array | - | Chart configuration parameter |
| gateway.parentRefs | array | - | Chart configuration parameter |
External Secrets(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| externalSecrets.enabled | boolean | - | Chart configuration parameter |
| externalSecrets.apiVersion | string | - | Chart configuration parameter Allowed: external-secrets.io/v1external-secrets.io/v1beta1 |
| externalSecrets.refreshInterval | string | - | Chart configuration parameter |
| externalSecrets.secretStoreRef.name | string | - | Chart configuration parameter |
| externalSecrets.secretStoreRef.kind | string | - | Chart configuration parameter Allowed: SecretStoreClusterSecretStore |
| externalSecrets.target.creationPolicy | string | - | Chart configuration parameter Allowed: OwnerOrphanMergeNone |
| externalSecrets.data | array | - | Chart configuration parameter |
No schema parameters match your search
Try searching for a different keyword or reset the filter.