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/dolibarrcontainer - 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/documentsand/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
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.
Admin
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.
Database
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.
MySQL Subchart
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.
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
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.
Ingress
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.
Network Policy and Service Account
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.
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
documentsandcustomif 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 SyncedVerified 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
Dolibarr 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 settings shared by the chart. |
Name Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nameOverride | string | - | Override the chart name used in resource names |
Fullname Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| fullnameOverride | string | - | Override the full release name used in resource names |
Common Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonLabels | object | - | Labels added to every resource created by this chart |
Image(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| image.repository | string | - | Container image repository |
| image.tag | string | - | Container image tag (defaults to appVersion) |
| image.pullPolicy | string | - | Image pull policy Allowed: AlwaysIfNotPresentNever |
Image Pull Secrets(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| imagePullSecrets | array | - | Image pull secrets for private registries |
Container Ports(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| containerPorts.http | integer | - | HTTP port listened to by Apache inside the container |
Dolibarr(10)
| Parameter | Type | Default | Description |
|---|---|---|---|
| dolibarr.siteUrl | string | - | Full external URL of the site |
| dolibarr.companyName | string | - | Company name for Dolibarr setup |
| dolibarr.companyCountryCode | string | - | ISO country code for the company |
| dolibarr.auth | string | - | Authentication method |
| dolibarr.enableModules | string | - | Comma-separated list of modules to enable |
| dolibarr.installAuto | boolean | - | Enable automatic installation on first run |
| dolibarr.initDemo | boolean | - | Initialize with demo data |
| dolibarr.prod | boolean | - | Enable production mode |
| dolibarr.timezone | string | - | Application timezone |
| dolibarr.extraEnv | array | - | Additional environment variables for the container |
Admin(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| admin.login | string | - | Admin username |
| admin.password | string | - | Admin password |
| admin.existingSecret | string | - | Existing secret containing the admin password |
| admin.existingSecretPasswordKey | string | - | Key in the existing secret for the admin password |
Runtime(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| runtime.existingSecret | string | - | Existing secret containing the instance unique ID |
| runtime.existingSecretInstanceUniqueIdKey | string | - | Key in the existing secret for the instance unique ID |
| runtime.instanceUniqueId | string | - | Instance unique identifier |
Database(9)
| Parameter | Type | Default | Description |
|---|---|---|---|
| database.mode | string | - | Database mode selection Allowed: autoexternalmysql |
| database.external.host | string | - | External database hostname |
| database.external.port | integer | - | External database port |
| database.external.name | string | - | Database name |
| database.external.username | string | - | Database username |
| database.external.password | string | - | Database password |
| database.external.existingSecret | string | - | Existing secret for the database password |
| database.external.existingSecretPasswordKey | string | - | Key in the existing secret for the database password |
| database.external.ssl | boolean | - | Enable SSL for database connection |
Mysql(17)
| Parameter | Type | Default | Description |
|---|---|---|---|
| mysql.enabled | boolean | - | Deploy MySQL as a subchart |
| mysql.architecture | string | - | MySQL architecture Allowed: standalonereplication |
| mysql.auth.database | string | - | Database name created on first run |
| mysql.auth.username | string | - | Database username created on first run |
| mysql.auth.password | string | - | Database password |
| mysql.auth.rootPassword | string | - | Root password |
| mysql.auth.existingSecret | string | - | Existing MySQL auth secret used by the bundled MySQL subchart |
| mysql.auth.existingSecretUserPasswordKey | string | - | Key in the MySQL auth secret for the application user password |
| mysql.auth.existingSecretRootPasswordKey | string | - | Key in the MySQL auth secret for the root password |
| mysql.auth.existingSecretReplicationPasswordKey | string | - | Key in the MySQL auth secret for the replication password |
| mysql.standalone.persistence.enabled | boolean | - | Enable persistence for MySQL data |
| mysql.standalone.persistence.size | string | - | PVC size for MySQL |
| mysql.standalone.resources.requests.cpu | string | - | Chart configuration parameter |
| mysql.standalone.resources.requests.memory | string | - | Chart configuration parameter |
| mysql.standalone.resources.limits.cpu | string | - | Chart configuration parameter |
| mysql.standalone.resources.limits.memory | string | - | Chart configuration parameter |
| mysql.startupProbe.initialDelaySeconds | integer | - | Initial delay before the MySQL startup probe starts |
Persistence(12)
| Parameter | Type | Default | Description |
|---|---|---|---|
| persistence.documents.enabled | boolean | - | Enable persistence for documents |
| persistence.documents.storageClass | string | - | Storage class |
| persistence.documents.accessMode | string | - | Access mode for the PVC |
| persistence.documents.size | string | - | Size of the persistent volume |
| persistence.documents.existingClaim | string | - | Use an existing PVC |
| persistence.documents.annotations | object | - | Annotations for the PVC |
| persistence.custom.enabled | boolean | - | Enable persistence for custom modules |
| persistence.custom.storageClass | string | - | Storage class |
| persistence.custom.accessMode | string | - | Access mode for the PVC |
| persistence.custom.size | string | - | Size of the persistent volume |
| persistence.custom.existingClaim | string | - | Use an existing PVC |
| persistence.custom.annotations | object | - | Annotations for the PVC |
Php(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| php.memoryLimit | string | - | PHP memory limit |
| php.uploadMaxFilesize | string | - | Maximum upload file size |
| php.postMaxSize | string | - | Maximum POST size |
| php.maxExecutionTime | string | - | Maximum execution time in seconds |
Resources(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| resources.requests.cpu | string | - | Chart configuration parameter |
| resources.requests.memory | string | - | Chart configuration parameter |
| resources.limits.cpu | string | - | Chart configuration parameter |
| resources.limits.memory | string | - | Chart configuration parameter |
Pod Security(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podSecurityContext.seccompProfile.type | string | - | Chart configuration parameter |
Container Security(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| securityContext.allowPrivilegeEscalation | boolean | - | Chart configuration parameter |
| securityContext.capabilities.drop | array | - | Chart configuration parameter |
| securityContext.capabilities.add | array | - | Chart configuration parameter |
Wait For Database(8)
| Parameter | Type | Default | Description |
|---|---|---|---|
| waitForDatabase.resources.requests.cpu | string | - | Chart configuration parameter |
| waitForDatabase.resources.requests.memory | string | - | Chart configuration parameter |
| waitForDatabase.resources.limits.cpu | string | - | Chart configuration parameter |
| waitForDatabase.resources.limits.memory | string | - | Chart configuration parameter |
| waitForDatabase.securityContext.allowPrivilegeEscalation | boolean | - | Chart configuration parameter |
| waitForDatabase.securityContext.runAsNonRoot | boolean | - | Chart configuration parameter |
| waitForDatabase.securityContext.runAsUser | integer | - | Chart configuration parameter |
| waitForDatabase.securityContext.capabilities.drop | array | - | Chart configuration parameter |
Startup Probe(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| startupProbe.enabled | boolean | - | Enable startup probe |
| startupProbe.path | string | - | HTTP GET probe path |
| startupProbe.initialDelaySeconds | integer | - | Initial delay before probe starts |
| startupProbe.periodSeconds | integer | - | Probe check interval |
| startupProbe.timeoutSeconds | integer | - | Probe timeout |
| startupProbe.failureThreshold | integer | - | Failures before marking unhealthy |
Liveness Probe(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| livenessProbe.enabled | boolean | - | Enable liveness probe |
| livenessProbe.path | string | - | HTTP GET probe path |
| livenessProbe.initialDelaySeconds | integer | - | Initial delay before probe starts |
| livenessProbe.periodSeconds | integer | - | Probe check interval |
| livenessProbe.timeoutSeconds | integer | - | Probe timeout |
| livenessProbe.failureThreshold | integer | - | Failures before marking unhealthy |
Readiness Probe(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| readinessProbe.enabled | boolean | - | Enable readiness probe |
| readinessProbe.path | string | - | HTTP GET probe path |
| readinessProbe.initialDelaySeconds | integer | - | Initial delay before probe starts |
| readinessProbe.periodSeconds | integer | - | Probe check interval |
| readinessProbe.timeoutSeconds | integer | - | Probe timeout |
| readinessProbe.failureThreshold | integer | - | Failures before marking unhealthy |
Service & Networking(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| service.type | string | - | Service type Allowed: ClusterIPNodePortLoadBalancer |
| service.port | integer | - | HTTP service port |
| service.annotations | object | - | Annotations for the Service |
| service.ipFamilyPolicy | stringnull | - | Service IP family policy Allowed: SingleStackPreferDualStackRequireDualStacknull |
| service.ipFamilies | array | - | Service IP families override |
Ingress(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| ingress.enabled | boolean | - | Enable ingress |
| ingress.ingressClassName | string | - | Ingress class name |
| ingress.annotations | object | - | Ingress annotations |
| ingress.hosts | array | - | Ingress hosts |
| ingress.tls | array | - | Ingress TLS configuration |
Service Account(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| serviceAccount.create | boolean | - | Create a dedicated ServiceAccount |
| serviceAccount.name | string | - | Name override |
| serviceAccount.annotations | object | - | Annotations for the ServiceAccount |
| serviceAccount.automountServiceAccountToken | boolean | - | Mount the Kubernetes API token in the Dolibarr pod |
Network Policy(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| networkPolicy.enabled | boolean | - | Create an ingress NetworkPolicy |
| networkPolicy.ingressFrom | array | - | Custom NetworkPolicy ingress peers |
Node Selector(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nodeSelector | object | - | Node selector for pod scheduling |
Tolerations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| tolerations | array | - | Tolerations for pod scheduling |
Affinity(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| affinity | object | - | Affinity rules for pod scheduling |
Topology Spread Constraints(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| topologySpreadConstraints | array | - | Topology spread constraints |
Priority Class Name(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| priorityClassName | string | - | Priority class name |
Termination Grace Period Seconds(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| terminationGracePeriodSeconds | integer | - | Grace period for shutdown in seconds |
Pod Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podLabels | object | - | Additional labels for the pod |
Pod Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podAnnotations | object | - | Additional annotations for the pod |
Extra Volume Mounts(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumeMounts | array | - | Additional volume mounts for the container |
Extra Volumes(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumes | array | - | Additional volumes for the pod |
Extra Manifests(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraManifests | array | - | Extra Kubernetes manifests to deploy alongside the chart |
Backup(21)
| Parameter | Type | Default | Description |
|---|---|---|---|
| backup.enabled | boolean | - | Enable scheduled MySQL backups to S3-compatible storage |
| backup.schedule | string | - | Cron schedule for the backup job |
| backup.suspend | boolean | - | Suspend the CronJob |
| backup.concurrencyPolicy | string | - | CronJob concurrency policy Allowed: AllowForbidReplace |
| backup.successfulJobsHistoryLimit | integer | - | Number of successful jobs to keep |
| backup.failedJobsHistoryLimit | integer | - | Number of failed jobs to keep |
| backup.backoffLimit | integer | - | Number of retries before marking job as failed |
| backup.archivePrefix | string | - | Prefix for the dump filename |
| backup.images.mysql | string | - | MySQL client image for mysqldump |
| backup.images.uploader | string | - | MinIO client image for S3 upload |
| backup.resources | object | - | Resource requests/limits for backup containers |
| backup.database.mysqldumpArgs | string | - | Extra arguments passed to mysqldump |
| backup.s3.endpoint | string | - | S3 endpoint URL |
| backup.s3.bucket | string | - | S3 bucket name |
| backup.s3.prefix | string | - | Object prefix inside the bucket |
| backup.s3.createBucketIfNotExists | boolean | - | Create the bucket if it does not exist |
| backup.s3.existingSecret | string | - | Use an existing secret for S3 credentials |
| backup.s3.existingSecretAccessKeyKey | string | - | Key in the existing secret for the access key |
| backup.s3.existingSecretSecretKeyKey | string | - | Key in the existing secret for the secret key |
| backup.s3.accessKey | string | - | S3 access key (ignored when existingSecret is set) |
| backup.s3.secretKey | string | - | S3 secret key (ignored when existingSecret is set) |
Gateway(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| gateway.enabled | boolean | false | Chart configuration parameter |
| gateway.annotations | object | - | Chart configuration parameter |
| gateway.parentRefs | array | - | Chart configuration parameter |
| gateway.hostnames | array | - | Chart configuration parameter |
| gateway.path | string | - | Chart configuration parameter |
| gateway.pathType | string | - | Chart configuration parameter Allowed: ExactPathPrefixRegularExpression |
External Secrets(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| externalSecrets.enabled | boolean | false | Chart configuration parameter |
| externalSecrets.apiVersion | string | - | Chart configuration parameter |
| 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.