ERPNext Logo

Installing ERPNext 14 on Debian 12

ERPNext is an amazing, free and open-source ERP system built using the Frappe Bench framework. It is scale-able, simple to use and quite beautiful. It is also quite difficult to install outside of the easy-installers which do not play nice with Debian.

In my case, I have an LXC Container on Proxmox VE, running Debian 12, MariaDB and Nginx, already serving several apps configured to various subdomains, which means that this existing server is ideally suited to install the ERPNext website on, this is achieved by using DNS_Multitenant in bench.

It should be noted that if, like me, you use Proxmox VE with an LXC Container, you will need to enable nested virtualization in the container in order for redis-server to work. Simply edit the Container Config File (/etc/pve/lxc/.conf) and add a line at the bottom: features: nesting=1 (Or enable nesting in the Proxmox WebUI).

In this tutorial, we will work through the steps necessary to implement ERPNext on a fresh Debian Install (LXC Container but works on Bare Metal or VM).

This how-to assumes that you are logged in as root and have already configured your DNS server to forward the relevant subdomain to the correct server.

Step 1 – Install Pre-requisite Software Packages:

Install the required packages:

apt install build-essential git python3-dev python3-setuptools python3-pip python3-distutils python3-venv supervisor software-properties-common mariadb-server mariadb-client xvfb libfontconfig1 wkhtmltopdf libmariadb-dev curl nginx sudo build-essential --no-install-recommends

Install Node.js and NPM (version 16+ is required)

curl -sL | bash -
apt install nodejs npm --no-install-recommends -y

Install the Yarn NMP Package:

npm install -g yarn

Install Redis from the Redis repo (The version shipping with Debian is outdated)

curl -fsSL | gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] $(lsb_release -cs) main" | tee /etc/apt/sources.list.d/redis.list
apt install redis-server --no-install-recommends
systemctl enable --now redis-server

Step 2 – Configure MariaDB

  1. Configure MariaDB for use with Frappe-Bench:
    • Edit your mariadb.cnf file to enable the Baracuda engine for innodb:

      nano /etc/mysql/mariadb.conf.d/50-server.cnf
    • Insert the following below the [mysqld] block:

      character-set-client-handshake = FALSE
      character-set-server = utf8mb4
      collation-server = utf8mb4_unicode_ci

    • Insert the following [mysql] block:

      default-character-set = utf8mb4

    • Restart Mariadb

      systemctl restart mariadb
  2. Run the MySQL Secure Installation Command and configure a root password:


Step 3 – Create a Linux User to run your Bench

  1. Create a Linux user with sudo priveleges to run your Bench instance:

    adduser frappe
  2. Configure with any password, however make a note in case you need to use it in future.

    usermod -aG sudo frappe

Step 4 – Install Bench

  1. Login to Debian with your newly created bench user, or, as root, su to the bench user:

    su frappe
  2. Install Bench:

    sudo pip install frappe-bench ansible --break-system-packages

Step 5 – Create a Bench instance for your ERPNext installation

  1. Create a Bench instance, name it anything you’d like, however I am going to use frappe-bench for ease of reference:
    • Make sure you are in your home directory:

    • Initiate a version 14 bench:

      bench init --frappe-branch version-14 frappe-bench
  2. Make sure that the bench folder is executable:

    chmod -R o+rx ./frappe-bench/
  3. Switch to the newly created Bench instance folder, the name you chose at point 1 above will be the name of the bench folder:

    cd frappe-bench
  4. You can test whether it installed correctly with the following command, which should return the currently installed Bench version, 5.3.0 at the time of updating this how-to:

    bench --version
  5. Configure Bench to use the default Redis configuration:

    bench set-config -g redis_cache redis://
    bench set-config -g redis_queue redis://
    bench set-config -g redis_socketio redis://

Step 6 – Download the ERPNExt app for Bench:

  1. If you chose to go with the standard (Developer) branch during step 5:

    bench get-app --branch version-14 erpnext

Step 7 – Create a site which will host your ERPNext instance:

  1. Note that you should use the fqdn (Fully Qualified Domain Name) which you set up in DNS. For this example we will use The MariaDB User you created at point 2 in Step 2 can be substituted if you did not use bench as the username for your instance.
  2. Create the Bench site:

    bench new-site
    • Provide the MariaDB root password which you configured at Step 2 here.
  3. During the installation, the installer will ask you to create an Administrator Password, make a note of the password you choose as you will need it to log in to ERPNext once it is installed.

Step 8 – Install the ERPNext App in your Site

  1. Install the ERPNext Bench App in the Bench Site you created in Step 7 above:

    bench --site install-app erpnext
  2. You can now manually start Bench using the command bench start, however we won’t be doing that as we want it to start automatically, which is done by setting up Bench for Production Use.

Step 7 – Set up Bench for production use

  1. In order to use your ERPNext installation in a production environment, you should automate starting, maintenance and various other tasks, luckily Bench can do this for you by making use of Supervisor, which we installed during Step 1:

    sudo bench setup production bench
  2. Enable Bench scheduler:

    bench --site enable-scheduler

Step 8 – BUGFIX – Supervisor

There appears to be an issue with the installation wherein configuring production does not properly enable Supervisor on Debain 12. The workaround is to just point supervisor to the correct .conf file.

  1. Stop Supervisor

    sudo supervisorctl stop all
  2. Create a synlink for the Frappe-Bench supervisorctl.conf file in the Supervisor conf.d folder:

    sudo ln -sf /home/frappe/frappe-bench/config/supervisor.conf /etc/supervisor/conf.d/frappe-bench.conf
  3. Reconfigure Supervisor:

    sudo supervisorctl reread
    sudo supervisorctl update
    sudo supervisorctl start all

Step 9 – Fix CSS

  1. Due to the way in which Debian 12 works wit permissions and python3, we need to fix the permissions of the frappe user folder:

    sudo chmod 701 /home/frappe

And you are done, now simply point your browser at the site you configured: and it should show you the login page. Use Administrator as the username and the password which you configured during point 3 in Step 7.

Edit – Updating your Bench Sites

When you need to update your Bench sites to the latest version, login as the bench user and cd to your bench instance folder:

cd frappe-bench
bench update

Edit – Updating Frappe Bench

From time to time you might need to update Frappe-Bench, the correct method is to login as the bench user you have created and running the following command:

sudo pip install --upgrade frappe-bench

Edit – Restoring from backups

Make sure that you upload the backup files to the /tmp folder, note that there are three (3) files, being …-database.sql.gz which contains the backup of your ERPNext data, …-files.tar which contains your public files and …-private-files.tar which contains your private files. Again, this must be run from your bench folder:

cd frappe-bench
bench --site --force restore /tmp/...-database.sql.gz --with-private-files /tmp/...-private-files.tar --with-public-files /tmp/...-files.tar

Edit – Restart from scratch

If you want to delete all the setup and configuration (Such as when testing) but don’t want to go through all the steps of starting up a new setup, you can simply reset the database as follows:

cd frappe-bench
bench --site --force reinstall


Leave a Reply

Your email address will not be published. Required fields are marked *