Skip to content
Dolibarr icon
v1.2.25App: v24.0.2Pinned DigestS3 Backup Ready

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

Dolibarr

A Helm chart for deploying Dolibarr ERP/CRM on Kubernetes using the official dolibarr/dolibarr Docker image.

Installation

HTTPS Repository

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

OCI Registry

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

Quick Start

helm install dolibarr oci://ghcr.io/helmforgedev/helm/dolibarr \
  --set mysql.auth.password=dbpassword \
  --set dolibarr.companyName="Example Corp"

Features

  • Official Dolibarr Image — based on the official dolibarr/dolibarr container
  • MySQL Subchart — bundled HelmForge MySQL dependency by default
  • External MySQL/MariaDB — connect to an existing managed database
  • Auto Installation — unattended setup through DOLI_* environment variables
  • Persistent Storage — separate PVCs for /var/www/documents and /var/www/html/custom
  • Ingress Support — configurable ingress with TLS for HTTPS access
  • Gateway API Support — optional HTTPRoute for clusters using Gateway API
  • S3 Backups — optional mysqldump CronJob for S3-compatible storage
  • Secret Preservation — admin, runtime, and database secrets preserved across upgrades via lookup
  • Network Isolation — ingress is limited to the named Dolibarr HTTP port by default
  • Runtime Validation — the chart verifies the real Apache listener and a Dolibarr HTTP response on k3d

Architecture

The chart runs one Dolibarr Deployment because its documents and custom-module volumes default to ReadWriteOnce. A named Service port routes to Apache, whose real listener is configured from containerPorts.http. The application connects either to the bundled HelmForge MySQL StatefulSet or to an operator-managed MySQL/MariaDB endpoint. See DESIGN.md for trust boundaries and design decisions.

Configuration

Minimal

mysql:
  enabled: true
  auth:
    password: "change-me"

dolibarr:
  companyName: "Example Corp"

Production

dolibarr:
  siteUrl: "https://erp.example.com"
  companyName: "Example Corp"
  companyCountryCode: "US"
  enableModules: "societe,produit,service,propal,commande,facture"

mysql:
  enabled: true
  auth:
    existingSecret: dolibarr-mysql
  standalone:
    persistence:
      size: 20Gi

persistence:
  documents:
    size: 20Gi
  custom:
    size: 5Gi

php:
  memoryLimit: 512M
  uploadMaxFilesize: 64M
  postMaxSize: 64M
  maxExecutionTime: "300"

ingress:
  enabled: true
  ingressClassName: traefik
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: erp.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: dolibarr-tls
      hosts:
        - erp.example.com

External Database

mysql:
  enabled: false

database:
  mode: external
  external:
    host: mariadb.example.com
    port: 3306
    name: dolibarr
    username: dolibarr
    existingSecret: dolibarr-db
    existingSecretPasswordKey: password

Examples

Ready-to-adapt values files are available for common deployment models:

To validate an example before applying it:

helm template dolibarr . -f examples/production.yaml

Parameters

Upgrade to 24.0.2

Dolibarr 24.0.2 is a patch release on the 24.0 line. It fixes authorization, failed-upload reporting, API-call counting, SQL-prefix handling, table creation and multiple business workflows. Back up the database and both the documents and custom PVCs before upgrading. The 24.0 major-upgrade cautions still apply: review removed or renamed modules, hooks, configuration variables and integrations, then test the upgrade in staging before reusing production storage. In particular, the Login API is disabled by default in 24.0 unless API_ENABLE_LOGIN_API is enabled, so integrations that use it can stop authenticating.

Review the official Dolibarr 24.0.2 release notes and the 24.0.0 migration notes before production rollout.

Application

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Admin

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Database

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

MySQL Subchart

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

When upgrading from chart releases that used mysql.primary.*, migrate those values to mysql.standalone.*. The chart fails fast if mysql.primary is still present so persistence and resource settings are not silently ignored by the HelmForge MySQL 2.x dependency.

Persistence

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Ingress

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Network Policy and Service Account

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Security

The pod does not receive a Kubernetes API token by default. A NetworkPolicy selects only the Dolibarr workload and exposes only its named HTTP port. Secrets generated by the chart are preserved with lookup, and their rendered checksum is included in the pod template so intentional value changes trigger a rollout.

The official image must start as root to perform first-run ownership and Apache setup, and it requires writable application paths. Consequently, runAsNonRoot and readOnlyRootFilesystem are not safe chart defaults. Apply a stricter securityContext only after validating a compatible derivative image and storage layout. TLS termination, external-database controls, Secret rotation, and egress restrictions remain operator responsibilities.

Security Scan: dolibarr

Framework Score
MITRE + NSA + SOC2 87.878784%
MITRE 100.00%
NSA 82.50%
SOC2 90.00%

The remaining findings reflect the official Dolibarr container's root-based bootstrap and writable application filesystem.

Troubleshooting

If the pod remains in Init, inspect the wait-for-db init-container logs and verify the selected database hostname, port, and Secret key. If readiness fails, confirm that containerPorts.http is free and inspect the generated Apache files:

kubectl logs deploy/dolibarr -c wait-for-db
kubectl logs deploy/dolibarr -c dolibarr
kubectl exec deploy/dolibarr -c dolibarr -- grep -E '^(Listen|<VirtualHost)' \
  /etc/apache2/ports.conf /etc/apache2/sites-available/000-default.conf

For missing uploads or modules, verify that both PVCs are Bound and that the corresponding existingClaim names are correct. For failed backups, inspect the CronJob-created Job and confirm the S3 endpoint, bucket, and credential Secret.

Notes

  • this chart intentionally supports MySQL/MariaDB only for automated setups
  • PostgreSQL is not included because the official container workflow is not equivalent to the unattended MySQL path
  • persist both documents and custom if you plan to keep generated artifacts, modules, or themes across upgrades
  • built-in Dolibarr cron is intentionally not enabled by this first chart release because it still needs a stable Kubernetes validation path
  • the default startup probe delay accounts for the initial database import performed by the official container on a fresh deployment

More Information

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
  user[User] --> ingress[Ingress or HTTPRoute]
  ingress --> svc[Dolibarr Service]
  svc --> app[Dolibarr Deployment]
  app --> documents[(Documents PVC)]
  app --> custom[(Custom modules PVC)]
  app --> dbsvc[MySQL Service]
  dbsvc --> mysql[HelmForge MySQL StatefulSet]
  mysql --> mysqlpvc[(MySQL PVC)]
  secrets[Generated Secrets] --> app
  secrets --> mysql
Official Contractvalues.schema.json

Dolibarr Values Schema Reference

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

163 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Global settings shared by the chart.

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring-Override the chart name used in resource names

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring-Override the full release name used in resource names

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsobject-Labels added to every resource created by this chart

Image(3)

ParameterTypeDefaultDescription
image.repositorystring-Container image repository
image.tagstring-Container image tag (defaults to appVersion)
image.pullPolicystring-Image pull policy
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Image pull secrets for private registries

Container Ports(1)

ParameterTypeDefaultDescription
containerPorts.httpinteger-HTTP port listened to by Apache inside the container

Dolibarr(10)

ParameterTypeDefaultDescription
dolibarr.siteUrlstring-Full external URL of the site
dolibarr.companyNamestring-Company name for Dolibarr setup
dolibarr.companyCountryCodestring-ISO country code for the company
dolibarr.authstring-Authentication method
dolibarr.enableModulesstring-Comma-separated list of modules to enable
dolibarr.installAutoboolean-Enable automatic installation on first run
dolibarr.initDemoboolean-Initialize with demo data
dolibarr.prodboolean-Enable production mode
dolibarr.timezonestring-Application timezone
dolibarr.extraEnvarray-Additional environment variables for the container

Admin(4)

ParameterTypeDefaultDescription
admin.loginstring-Admin username
admin.passwordstring-Admin password
admin.existingSecretstring-Existing secret containing the admin password
admin.existingSecretPasswordKeystring-Key in the existing secret for the admin password

Runtime(3)

ParameterTypeDefaultDescription
runtime.existingSecretstring-Existing secret containing the instance unique ID
runtime.existingSecretInstanceUniqueIdKeystring-Key in the existing secret for the instance unique ID
runtime.instanceUniqueIdstring-Instance unique identifier

Database(9)

ParameterTypeDefaultDescription
database.modestring-Database mode selection
Allowed:autoexternalmysql
database.external.hoststring-External database hostname
database.external.portinteger-External database port
database.external.namestring-Database name
database.external.usernamestring-Database username
database.external.passwordstring-Database password
database.external.existingSecretstring-Existing secret for the database password
database.external.existingSecretPasswordKeystring-Key in the existing secret for the database password
database.external.sslboolean-Enable SSL for database connection

Mysql(17)

ParameterTypeDefaultDescription
mysql.enabledboolean-Deploy MySQL as a subchart
mysql.architecturestring-MySQL architecture
Allowed:standalonereplication
mysql.auth.databasestring-Database name created on first run
mysql.auth.usernamestring-Database username created on first run
mysql.auth.passwordstring-Database password
mysql.auth.rootPasswordstring-Root password
mysql.auth.existingSecretstring-Existing MySQL auth secret used by the bundled MySQL subchart
mysql.auth.existingSecretUserPasswordKeystring-Key in the MySQL auth secret for the application user password
mysql.auth.existingSecretRootPasswordKeystring-Key in the MySQL auth secret for the root password
mysql.auth.existingSecretReplicationPasswordKeystring-Key in the MySQL auth secret for the replication password
mysql.standalone.persistence.enabledboolean-Enable persistence for MySQL data
mysql.standalone.persistence.sizestring-PVC size for MySQL
mysql.standalone.resources.requests.cpustring-Chart configuration parameter
mysql.standalone.resources.requests.memorystring-Chart configuration parameter
mysql.standalone.resources.limits.cpustring-Chart configuration parameter
mysql.standalone.resources.limits.memorystring-Chart configuration parameter
mysql.startupProbe.initialDelaySecondsinteger-Initial delay before the MySQL startup probe starts

Persistence(12)

ParameterTypeDefaultDescription
persistence.documents.enabledboolean-Enable persistence for documents
persistence.documents.storageClassstring-Storage class
persistence.documents.accessModestring-Access mode for the PVC
persistence.documents.sizestring-Size of the persistent volume
persistence.documents.existingClaimstring-Use an existing PVC
persistence.documents.annotationsobject-Annotations for the PVC
persistence.custom.enabledboolean-Enable persistence for custom modules
persistence.custom.storageClassstring-Storage class
persistence.custom.accessModestring-Access mode for the PVC
persistence.custom.sizestring-Size of the persistent volume
persistence.custom.existingClaimstring-Use an existing PVC
persistence.custom.annotationsobject-Annotations for the PVC

Php(4)

ParameterTypeDefaultDescription
php.memoryLimitstring-PHP memory limit
php.uploadMaxFilesizestring-Maximum upload file size
php.postMaxSizestring-Maximum POST size
php.maxExecutionTimestring-Maximum execution time in seconds

Resources(4)

ParameterTypeDefaultDescription
resources.requests.cpustring-Chart configuration parameter
resources.requests.memorystring-Chart configuration parameter
resources.limits.cpustring-Chart configuration parameter
resources.limits.memorystring-Chart configuration parameter

Pod Security(1)

ParameterTypeDefaultDescription
podSecurityContext.seccompProfile.typestring-Chart configuration parameter

Container Security(3)

ParameterTypeDefaultDescription
securityContext.allowPrivilegeEscalationboolean-Chart configuration parameter
securityContext.capabilities.droparray-Chart configuration parameter
securityContext.capabilities.addarray-Chart configuration parameter

Wait For Database(8)

ParameterTypeDefaultDescription
waitForDatabase.resources.requests.cpustring-Chart configuration parameter
waitForDatabase.resources.requests.memorystring-Chart configuration parameter
waitForDatabase.resources.limits.cpustring-Chart configuration parameter
waitForDatabase.resources.limits.memorystring-Chart configuration parameter
waitForDatabase.securityContext.allowPrivilegeEscalationboolean-Chart configuration parameter
waitForDatabase.securityContext.runAsNonRootboolean-Chart configuration parameter
waitForDatabase.securityContext.runAsUserinteger-Chart configuration parameter
waitForDatabase.securityContext.capabilities.droparray-Chart configuration parameter

Startup Probe(6)

ParameterTypeDefaultDescription
startupProbe.enabledboolean-Enable startup probe
startupProbe.pathstring-HTTP GET probe path
startupProbe.initialDelaySecondsinteger-Initial delay before probe starts
startupProbe.periodSecondsinteger-Probe check interval
startupProbe.timeoutSecondsinteger-Probe timeout
startupProbe.failureThresholdinteger-Failures before marking unhealthy

Liveness Probe(6)

ParameterTypeDefaultDescription
livenessProbe.enabledboolean-Enable liveness probe
livenessProbe.pathstring-HTTP GET probe path
livenessProbe.initialDelaySecondsinteger-Initial delay before probe starts
livenessProbe.periodSecondsinteger-Probe check interval
livenessProbe.timeoutSecondsinteger-Probe timeout
livenessProbe.failureThresholdinteger-Failures before marking unhealthy

Readiness Probe(6)

ParameterTypeDefaultDescription
readinessProbe.enabledboolean-Enable readiness probe
readinessProbe.pathstring-HTTP GET probe path
readinessProbe.initialDelaySecondsinteger-Initial delay before probe starts
readinessProbe.periodSecondsinteger-Probe check interval
readinessProbe.timeoutSecondsinteger-Probe timeout
readinessProbe.failureThresholdinteger-Failures before marking unhealthy

Service & Networking(5)

ParameterTypeDefaultDescription
service.typestring-Service type
Allowed:ClusterIPNodePortLoadBalancer
service.portinteger-HTTP service port
service.annotationsobject-Annotations for the Service
service.ipFamilyPolicystringnull-Service IP family policy
Allowed:SingleStackPreferDualStackRequireDualStacknull
service.ipFamiliesarray-Service IP families override

Ingress(5)

ParameterTypeDefaultDescription
ingress.enabledboolean-Enable ingress
ingress.ingressClassNamestring-Ingress class name
ingress.annotationsobject-Ingress annotations
ingress.hostsarray-Ingress hosts
ingress.tlsarray-Ingress TLS configuration

Service Account(4)

ParameterTypeDefaultDescription
serviceAccount.createboolean-Create a dedicated ServiceAccount
serviceAccount.namestring-Name override
serviceAccount.annotationsobject-Annotations for the ServiceAccount
serviceAccount.automountServiceAccountTokenboolean-Mount the Kubernetes API token in the Dolibarr pod

Network Policy(2)

ParameterTypeDefaultDescription
networkPolicy.enabledboolean-Create an ingress NetworkPolicy
networkPolicy.ingressFromarray-Custom NetworkPolicy ingress peers

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Node selector for pod scheduling

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Tolerations for pod scheduling

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Affinity rules for pod scheduling

Topology Spread Constraints(1)

ParameterTypeDefaultDescription
topologySpreadConstraintsarray-Topology spread constraints

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring-Priority class name

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger-Grace period for shutdown in seconds

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsobject-Additional labels for the pod

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Additional annotations for the pod

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Additional volume mounts for the container

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Additional volumes for the pod

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Extra Kubernetes manifests to deploy alongside the chart

Backup(21)

ParameterTypeDefaultDescription
backup.enabledboolean-Enable scheduled MySQL backups to S3-compatible storage
backup.schedulestring-Cron schedule for the backup job
backup.suspendboolean-Suspend the CronJob
backup.concurrencyPolicystring-CronJob concurrency policy
Allowed:AllowForbidReplace
backup.successfulJobsHistoryLimitinteger-Number of successful jobs to keep
backup.failedJobsHistoryLimitinteger-Number of failed jobs to keep
backup.backoffLimitinteger-Number of retries before marking job as failed
backup.archivePrefixstring-Prefix for the dump filename
backup.images.mysqlstring-MySQL client image for mysqldump
backup.images.uploaderstring-MinIO client image for S3 upload
backup.resourcesobject-Resource requests/limits for backup containers
backup.database.mysqldumpArgsstring-Extra arguments passed to mysqldump
backup.s3.endpointstring-S3 endpoint URL
backup.s3.bucketstring-S3 bucket name
backup.s3.prefixstring-Object prefix inside the bucket
backup.s3.createBucketIfNotExistsboolean-Create the bucket if it does not exist
backup.s3.existingSecretstring-Use an existing secret for S3 credentials
backup.s3.existingSecretAccessKeyKeystring-Key in the existing secret for the access key
backup.s3.existingSecretSecretKeyKeystring-Key in the existing secret for the secret key
backup.s3.accessKeystring-S3 access key (ignored when existingSecret is set)
backup.s3.secretKeystring-S3 secret key (ignored when existingSecret is set)

Gateway(6)

ParameterTypeDefaultDescription
gateway.enabledbooleanfalseChart configuration parameter
gateway.annotationsobject-Chart configuration parameter
gateway.parentRefsarray-Chart configuration parameter
gateway.hostnamesarray-Chart configuration parameter
gateway.pathstring-Chart configuration parameter
gateway.pathTypestring-Chart configuration parameter
Allowed:ExactPathPrefixRegularExpression

External Secrets(7)

ParameterTypeDefaultDescription
externalSecrets.enabledbooleanfalseChart configuration parameter
externalSecrets.apiVersionstring-Chart configuration parameter
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