How to Install ERPNext on AlmaLinux 9 or Rocky Linux 9 with Docker
Deploy ERPNext 16 on AlmaLinux 9 or Rocky Linux 9 with the official frappe_docker Compose files, automatic HTTPS, and a clear backup and update routine.
This guide installs ERPNext, the open-source ERP system built on the Frappe framework, on AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9. At the end you will have ERPNext 16 running in Docker containers with its own MariaDB and Redis, reachable at https://erp.example.com with an automatically issued Let's Encrypt certificate.
CentOS 7 reached end of life in June 2024, and ERPNext has moved on as well. The Frappe documentation describes a manual installation with the bench tool only for Debian 13 or newer, Ubuntu 24.04 or newer and macOS, and it advises against bare-metal installations for production in favour of the official Docker images. Current ERPNext also needs much newer components than a RHEL 9 system ships, so on this platform the container deployment from the frappe_docker repository is the supported route.
Requirements
- A server running AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9 and a user with
sudorights (deployin the examples). ERPNext starts around ten containers including the database, so give it several gigabytes of memory. - Docker Engine with Compose v2, and
git. - A DNS record such as
erp.example.compointing to the server, and ports 80 and 443 free and reachable from the internet. The bundled Traefik proxy uses them to obtain and renew the certificate.
For reference, this is what the Frappe documentation requires for a manual bench installation, and why it does not fit a RHEL 9 system:
| Component | Frappe 14 / 15 | Frappe 16 |
|---|---|---|
| Python | 3.10 or newer | 3.14 |
| Node.js | 18 or newer | 24 |
| MariaDB | 10.6.6 or newer | 11.8 |
| Redis or Valkey | 6 | 6 or newer |
Step 1: Install Docker Engine
Add Docker's repository and install the engine with the Compose plugin. Docker documents this repository for CentOS Stream 9; AlmaLinux 9 and Rocky Linux 9 are RHEL-compatible and use the same packages, although Docker does not list them as tested platforms.
sudo dnf -y install dnf-plugins-core git
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
Add your user to the docker group, then log out and back in:
sudo usermod -aG docker deploy
Step 2: Get frappe_docker and set the environment
Clone the repository and create your environment file from the example:
cd ~
git clone https://github.com/frappe/frappe_docker
cd frappe_docker
cp example.env .env
Edit .env and set these three values. Leave ERPNEXT_VERSION at the release the example file pins unless you need a specific one; it selects the tag of the frappe/erpnext image.
DB_PASSWORD=choose-a-long-random-password
LETSENCRYPT_EMAIL=admin@example.com
SITES_RULE=Host(`erp.example.com`)
DB_PASSWORD becomes the MariaDB root password; the example value 123 must not be used on a real server. SITES_RULE is a Traefik routing rule and the backticks around the host name are part of its syntax. For more than one host name, join the rules with ||.
Step 3: Generate the Compose file and start the containers
The repository contains a base compose.yaml and a set of override files. Combine the base with the MariaDB, Redis and HTTPS overrides and write the result to a single file outside the repository:
mkdir -p ~/gitops
docker compose -f compose.yaml \
-f overrides/compose.mariadb.yaml \
-f overrides/compose.redis.yaml \
-f overrides/compose.https.yaml \
config > ~/gitops/docker-compose.yml
Start the stack under a fixed project name. You need the same name in every later command.
docker compose --project-name erpnext -f ~/gitops/docker-compose.yml up -d
Wait until the database is running and the short-lived configurator container has exited:
docker compose --project-name erpnext -f ~/gitops/docker-compose.yml ps -a
Step 4: Create the site and install ERPNext
A Frappe "site" is one database plus its files. By default the site is selected by the host name of the request, so the site name must be exactly the domain you put in SITES_RULE. Create it and install the ERPNext app in one command; replace both passwords:
docker compose --project-name erpnext -f ~/gitops/docker-compose.yml exec backend \
bench new-site --mariadb-user-host-login-scope=% \
--db-root-password choose-a-long-random-password \
--install-app erpnext \
--admin-password choose-an-admin-password \
erp.example.com
--db-root-password is the DB_PASSWORD from step 2, and --admin-password sets the password of the built-in Administrator user. The command takes a few minutes while it creates the schema.
Step 5: Log in and verify
Open https://erp.example.com. Traefik requests the certificate on the first HTTPS request, so the very first load can take a moment. Log in as Administrator with the admin password from step 4 and complete the setup wizard (language, region, company and first user).
If the page does not come up, check the state of the containers and the proxy log. Ports published by Docker are opened by Docker itself, but a firewall in your hosting control panel must still allow TCP 80 and 443.
docker compose --project-name erpnext -f ~/gitops/docker-compose.yml ps
docker compose --project-name erpnext -f ~/gitops/docker-compose.yml logs --tail=50 proxy frontend
A "site not found" style error means the site name does not match the host name in the browser. List the existing sites with:
docker compose --project-name erpnext -f ~/gitops/docker-compose.yml exec backend bench list-sites
Backups and updates
Create a database and file backup of the site with bench, then copy the resulting files off the server. They are written inside the site's directory on the sites volume.
docker compose --project-name erpnext -f ~/gitops/docker-compose.yml exec backend \
bench --site erp.example.com backup --with-files
To update, take a backup, set the new release in ERPNEXT_VERSION in ~/frappe_docker/.env, regenerate the Compose file with the same command as in step 3, then pull, restart and migrate the site:
cd ~/frappe_docker
docker compose -f compose.yaml \
-f overrides/compose.mariadb.yaml \
-f overrides/compose.redis.yaml \
-f overrides/compose.https.yaml \
config > ~/gitops/docker-compose.yml
docker compose --project-name erpnext -f ~/gitops/docker-compose.yml pull
docker compose --project-name erpnext -f ~/gitops/docker-compose.yml down
docker compose --project-name erpnext -f ~/gitops/docker-compose.yml up -d
docker compose --project-name erpnext -f ~/gitops/docker-compose.yml exec backend \
bench --site erp.example.com migrate
Do not add -v to down: that flag deletes the volumes holding your database and files. Read the release notes before moving to a new major version.
Frequently asked questions
Can I install ERPNext with bench directly on AlmaLinux 9?
Not along a documented path. The Frappe installation guide covers Debian 13 or newer and Ubuntu 24.04 or newer, and ERPNext 16 expects Python 3.14, Node.js 24 and MariaDB 11.8. If you want a bench installation, use one of those distributions and follow the Frappe installation guide; keep in mind that Frappe itself recommends Docker for production.
Is there a quicker way to just try ERPNext?
Yes. In the frappe_docker directory run docker compose -f pwd.yml up -d, wait for the create-site container to finish and open port 8080. The login is Administrator with the password admin. The project describes this setup as intended for quick evaluation only, so do not put real data in it.
Can I add other Frappe apps such as HRMS?
Not to the stock image, which contains only Frappe and ERPNext. Additional apps require building a custom image that includes them; the procedure is described in the frappe_docker documentation.
Can I use my own reverse proxy instead of the bundled Traefik?
Yes. Replace overrides/compose.https.yaml with overrides/compose.noproxy.yaml when generating the Compose file. ERPNext is then published on port 8080 without TLS, and your own proxy has to forward to it and terminate HTTPS.