To self-host Dolibarr on a managed VPS is to keep your quotes, invoices, customers and stock on a server of your own, which our teams keep up to date and monitor day and night. Dolibarr is a free, open source ERP and CRM under the GPL-3.0 license, designed for companies of every size, foundations and freelancers. This guide follows its official Docker image at version 24.0.2, and we ran every command on a Simafri VPS before writing it: installation with Docker Compose and MariaDB, HTTPS, password security, modules, scheduled jobs, backups and updates.
By Simon Vasconcelos Lee
Published on 20 November 202613 minute read
dolibarr/dolibarr, MariaDB 12.3 and a cron service, with port 8080 published on 127.0.0.1 behind an HTTPS reverse proxy.DOLI_INSTANCE_UNIQUE_ID and DOLI_CRON_KEY in a .env file, and set DOLI_URL_ROOT to your public address.MAIN_SECURITY_HASH_ALGO to password_hash and activate “Encrypt passwords stored in database”: the image leaves both to you.mariadb-dump and an archive of the documents. To update, remove install.lock and change the image tag: the image migrates the database itself.Dolibarr is an ERP and CRM written in PHP, developed by a large community of contributors. It is organized in modules that you turn on one by one: about a hundred come with it, and more than a thousand add-ons are listed on the DoliStore, its official marketplace.
It speaks most major languages, handles several currencies and follows the tax rules of many countries. On our test VPS, set up for France, the first invoice line offered the French VAT rates, from 2.1% to 20%.
Dolibarr is published under the GNU General Public License, version 3 or any later version (GPL-3.0-or-later). You can use it free of charge, for your company, your association or your clients, copy it and modify it. If you distribute a modified version, you distribute its source code under the same license. The software is provided without warranty.
The add-ons of the DoliStore are published by their authors, some free and some paid, each under its own license. Nothing in this guide needs them.
The prerequisites page asks for MariaDB 10.3 or later and 128 MB of PHP memory, and counts less than 1 MB of database per 100 customers, vendors or invoices. Here is what we measured on our test VPS, after the installation and a first invoice:
Server size therefore depends on the number of users and on the other applications you run beside Dolibarr. On a managed VPS, tell us about your usage and we will recommend the right size.
The official image, dolibarr/dolibarr, contains Dolibarr, PHP and Apache. On its first start, it creates the database tables, the administrator and the company, and turns on the modules you list: there is no web installer to go through. It needs MariaDB or MySQL beside it. On a server with Docker Engine and its Compose plugin, installed from Docker’s repository for Ubuntu, create a folder such as /opt/dolibarr and put this compose.yaml in it, based on the examples of the image:
x-dolibarr: &dolibarr
image: dolibarr/dolibarr:24.0.2
restart: unless-stopped
environment: &dolibarr-env
DOLI_DB_HOST: mariadb
DOLI_DB_NAME: dolibarr
DOLI_DB_USER: dolibarr
DOLI_DB_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD in .env}
DOLI_URL_ROOT: https://dolibarr.example.com
DOLI_ADMIN_LOGIN: admin
DOLI_ADMIN_PASSWORD: ${DOLI_ADMIN_PASSWORD:?set DOLI_ADMIN_PASSWORD in .env}
DOLI_INSTANCE_UNIQUE_ID: ${DOLI_INSTANCE_UNIQUE_ID:?set DOLI_INSTANCE_UNIQUE_ID in .env}
DOLI_CRON_KEY: ${DOLI_CRON_KEY:?set DOLI_CRON_KEY in .env}
DOLI_CRON_USER: admin
DOLI_COMPANY_NAME: My Company
DOLI_COMPANY_COUNTRYCODE: FR
DOLI_ENABLE_MODULES: Societe,Propale,Facture,Banque,Cron
PHP_INI_DATE_TIMEZONE: Europe/Paris
volumes:
- dolibarr_documents:/var/www/documents
- dolibarr_custom:/var/www/html/custom
services:
mariadb:
image: mariadb:12.3
restart: unless-stopped
command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
environment:
MARIADB_DATABASE: dolibarr
MARIADB_USER: dolibarr
MARIADB_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD in .env}
MARIADB_RANDOM_ROOT_PASSWORD: "1"
volumes:
- mariadb_data:/var/lib/mysql
healthcheck:
test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
interval: 10s
timeout: 5s
retries: 10
dolibarr:
<<: *dolibarr
ports:
- "127.0.0.1:8080:80"
depends_on:
mariadb:
condition: service_healthy
cron:
<<: *dolibarr
environment:
<<: *dolibarr-env
DOLI_CRON: 1
depends_on:
- dolibarr
volumes:
mariadb_data:
dolibarr_documents:
dolibarr_custom:
The four secrets go in a .env file next to it, which Docker Compose reads on its own. Create it readable by root only, then start the stack:
umask 077
printf 'DB_PASSWORD=%s\nDOLI_ADMIN_PASSWORD=%s\nDOLI_INSTANCE_UNIQUE_ID=%s\nDOLI_CRON_KEY=%s\n' "$(openssl rand -hex 24)" "$(openssl rand -hex 12)" "$(openssl rand -hex 32)" "$(openssl rand -hex 24)" > .env
umask 022
docker compose up -d
docker compose ps
dolibarr serves the application, and cron runs Dolibarr’s scheduled jobs every five minutes with the same image. The x-dolibarr block holds what they share, so the image tag is written only once.127.0.0.1: the examples of the image publish port 80 on every address of the server. Published locally, Dolibarr is reachable only through the reverse proxy.admin and dolidbpass as passwords. The start script of the image reads these values without quotes and writes some of them into PHP and SQL, so hexadecimal is the safe choice.DOLI_INSTANCE_UNIQUE_ID is the key Dolibarr uses to encrypt the sensitive data it stores, in AES-256, according to its Security page. Without it, the image writes the same fixed value on every installation. Keep it secret, and keep it stable.DOLI_URL_ROOT is your public address, with https://: Dolibarr builds its links from it.DOLI_ADMIN_PASSWORD, DOLI_COMPANY_NAME, DOLI_COMPANY_COUNTRYCODE and DOLI_ENABLE_MODULES apply when the image creates the database; afterwards, the company and the modules are changed in Dolibarr itself. Cron is in the list so that the image gives the Scheduled jobs module the key of DOLI_CRON_KEY.PHP_INI_DATE_TIMEZONE is the time zone of dates and scheduled jobs, UTC by default: put yours, from the IANA list. Other PHP_INI_ variables set the memory and upload limits, 256 MB and 20 MB by default.lts tag of the image’s cron example pointed to when we tested, started in utf8mb4 with the utf8mb4_unicode_ci collation, the one Dolibarr declares in its configuration.latest. A full version, here 24.0.2, lets you choose when each update happens.mariadb_data holds the database, dolibarr_documents your PDFs, attachments and the install.lock file, and dolibarr_custom the add-ons you install.The first start creates the tables and the administrator; on our test VPS, Dolibarr answered about 30 seconds after its container started. To check that it is ready:
docker compose logs dolibarr | grep -E 'Activating module|Schema update'
curl -s http://127.0.0.1:8080/ | grep -o -E '<title>[^<]*</title>'
The first command lists the modules turned on and ends with “Schema update is not required ... Enjoy !”. The second returns the title of the login page, Login @ 24.0.2, with the version.
The container serves Dolibarr over HTTP, on port 8080 of the server. HTTPS is handled by a reverse proxy in front of it, which must forward the public Host header and X-Forwarded-Proto. We tested Caddy, installed from its official Debian and Ubuntu repository: it obtains the Let’s Encrypt certificate itself, renews it, and forwards these headers by default.
dolibarr.example.com {
reverse_proxy 127.0.0.1:8080
}
sudo systemctl reload caddy
X-Forwarded-Proto and marks its session cookie secure once served over HTTPS, which we checked on the login page. It takes the client address from X-Forwarded-For, which Caddy sets, for the login information shown on the home page.Open your address: Dolibarr shows its login page. Sign in with admin and the password generated in .env, which this command displays:
grep DOLI_ADMIN_PASSWORD /opt/dolibarr/.env
You land on the home page, with the version at the top right and the Setup menu on the left.
The image creates the database without Dolibarr’s web installer, and the installer is where Dolibarr normally turns on password encryption. On our test VPS, a password changed from a user card was kept in clear text in the database, next to an MD5 hash, and the Security page showed “Encrypt passwords stored in database: No”. Two settings take care of it, before you create any user.
MAIN_SECURITY_HASH_ALGO with the value password_hash, then click Add.On our VPS, the activation hashed the password that was stored in clear text and removed it, and every password changed afterwards was stored with password_hash, in bcrypt. The administrator signed in again each time, and the Security page showed “Encrypt passwords stored in database: Yes”.
compose.yaml.We then created a customer and an invoice from the browser: a free-text service line of 100.00 excluding tax, at 20% VAT, validated as FA2611-0001, with its PDF generated and downloaded.
Dolibarr sends invoices, proposals and password resets by email. Under Home, Setup, Emails, choose the sending method “SMTP/SMTPS socket library”, then enter the host of your SMTP relay, port 587 with STARTTLS, and the username and password of the sending account. On a Simafri VPS, applications send through an authenticated SMTP relay on port 587, which also gives your email the best deliverability.
The cron service runs cron_run_jobs.php every five minutes, as admin and with DOLI_CRON_KEY. On our test VPS, its log showed the jobs of the Scheduled jobs module at work: the purge of temporary files ran, and the generation of recurring invoices waited for its start date.
Everything lives in four places: the MariaDB database, the dolibarr_documents volume with your PDFs, attachments and install.lock, the dolibarr_custom volume with your add-ons, and your .env file. Keep the latter safe: DOLI_INSTANCE_UNIQUE_ID is needed to read the encrypted data of the database. The MariaDB image includes mariadb-dump, and the Dolibarr image includes tar:
docker compose exec -T mariadb sh -c 'exec mariadb-dump --single-transaction -u dolibarr -p"$MARIADB_PASSWORD" dolibarr' > dolibarr-$(date +%F).sql
docker compose exec -T dolibarr tar -C /var/www -czf - documents html/custom > files-$(date +%F).tar.gz
cp .env env-$(date +%F).bak
The dump reads the database password inside the container, so it never appears on the command line. Schedule this copy and send it off the server. Stored on the disk, the files are also included in the server’s nightly backups.
On the same installation, or on a new one with the same compose.yaml and .env where only docker compose up -d mariadb has run, stop the application, load the dump and the files, then start it again:
docker compose stop dolibarr cron
docker compose exec -T mariadb sh -c 'exec mariadb -u dolibarr -p"$MARIADB_PASSWORD" dolibarr' < dolibarr-2026-11-19.sql
docker compose run --rm --no-deps -T --entrypoint tar dolibarr -C /var/www -xzf - < files-2026-11-19.tar.gz
docker compose up -d
We tested the whole cycle on our VPS: dump and archive, the database actually dropped and the documents volume emptied, then the restore. The customer, the invoice FA2611-0001 and its PDF came back, and the administrator signed in again at once. Since install.lock is part of the archive, the image leaves the restored database as it is.
Dolibarr publishes a major version about twice a year and maintenance releases in between, and the image follows on Docker Hub with the same numbers. This guide pins 24.0.2, the most recent image there when we tested it: check the tags page for a newer release before you install. The image migrates the database itself, on one condition: the install.lock file must be removed first, otherwise the new version starts on the database as it is, without migrating it. Take a backup, then remove the file:
docker compose exec dolibarr rm -f /var/www/documents/install.lock
Change the image tag in the x-dolibarr block of compose.yaml, then pull the new image and recreate the containers:
docker compose pull
docker compose up -d
docker compose logs dolibarr | grep -E 'Database Version|Files Version|Migration'
backup-before-upgrade.sql, in the documents volume, ran the migration, logged “Migration successful”, then created install.lock again. The customer, the invoice and its PDF were all there in 24.0.2.migration_error.html, in the documents volume.develop tag follows the development branch of Dolibarr: stay on releases.Self-hosting means running the server on top of the application. On a managed VPS, our teams take charge of the server and proactively monitor your instance; Dolibarr remains your software, with your data and your settings.
| Topic | Our teams | You |
|---|---|---|
| The server | System and security updates, server interventions included | The timing that suits you |
| Monitoring | Server monitored 24/7, with intervention without waiting for your call | Your customers, your documents and your settings in Dolibarr |
| Dolibarr | Proactive monitoring: errors, slowdowns, database and disk space spotted, fix recommended | Its installation, updates, modules and settings, which you apply, yourself or through your AI assistant |
| Users | The server that carries them, monitored and backed up | Accounts, groups and permissions |
| Backups | Every night, encrypted and kept off the machine; restores included | Dolibarr’s own database dumps and document archives, and the restore request, when you need one |
| Migration | Your current server migrated, free of charge | The timing of the switch |
If you would rather have our teams work inside the application itself, that service is billed by the hour or at a fixed rate, with an estimate shared before the work starts.
With a Simafri Managed VPS, our teams keep your Dolibarr instance’s server up to date, monitor it day and night and step in without waiting for your call; they also proactively monitor your instance and recommend useful fixes, which you apply, yourself or through your AI assistant. Backups are encrypted every night and kept off the machine, restores are included, and migrating your current server is free.
Yes. Dolibarr is under the GPL-3.0-or-later license: you can run it for your company, your association or your clients with no license to buy. The add-ons of the DoliStore are free or paid, depending on their authors. What remains is the cost of the server that runs it.
Use the dolibarr/dolibarr image and MariaDB 12.3 in a compose.yaml, with a second service from the same image for the scheduled jobs. Put the two passwords, DOLI_INSTANCE_UNIQUE_ID and DOLI_CRON_KEY in a .env file, set DOLI_URL_ROOT to your https address, publish port 8080 on 127.0.0.1, run docker compose up -d, and put an HTTPS reverse proxy in front.
The image creates the administrator from DOLI_ADMIN_LOGIN and DOLI_ADMIN_PASSWORD on its first start, admin and admin if you set nothing. Generate a random password in .env, sign in with it, then change it from your user card once password encryption is on.
Once you turn it on. The image skips the web installer, which normally does it. Add the constant MAIN_SECURITY_HASH_ALGO with the value password_hash under Setup, Other Setup, then activate Encrypt passwords stored in database under Setup, Security, Passwords, before you create users.
Little. On our test VPS, Dolibarr used about 60 MB at rest and MariaDB about 270 MB, and the two images take about 730 MB of disk. The prerequisites ask for 128 MB of PHP memory; the image allows 256 MB per request.
Dump the database with mariadb-dump from the MariaDB container, archive /var/www/documents and /var/www/html/custom from the Dolibarr container, and keep a copy of your .env file. Restore the dump with mariadb and the archive with tar, the application stopped.
Take a backup, remove /var/www/documents/install.lock, change the image tag in compose.yaml, then run docker compose pull and docker compose up -d. The image saves the database, migrates it and creates install.lock again. As long as the file is there, the database is left as it is.
A managed VPS covers the server: system, security, monitoring and backups. Our teams also proactively monitor your instance and recommend useful fixes, which you apply. Work inside the application is billed by the hour or at a fixed rate.
Simafri
Let's talk about your project
Tell us what you need in a few words: we will get back to you quickly.
Thank you! Your request has been sent. We'll get back to you shortly.
Prefer email? Write to us at support@simafri.com.