How To Install ERPNext on Debian 13

ERPNext stands as one of the most powerful open-source Enterprise Resource Planning (ERP) solutions available today, offering businesses a comprehensive platform to manage accounting, inventory, human resources, customer relationships, and manufacturing processes. Built on the robust Frappe Framework, ERPNext delivers enterprise-grade functionality without the hefty licensing costs associated with proprietary alternatives. Debian 13, the latest stable release of one of the most reliable Linux distributions, provides an ideal foundation for hosting ERPNext due to its security-focused architecture, long-term support, and proven stability in production environments.

This comprehensive guide walks through every step required to successfully install ERPNext on Debian 13, from initial system preparation to accessing the web interface for the first time. Whether managing a small business or deploying enterprise-level solutions, this tutorial provides the knowledge needed to set up a production-ready ERPNext installation. The instructions assume basic familiarity with Linux command-line operations and SSH access to a Debian 13 server.

Understanding ERPNext and Its Architecture

ERPNext operates on the Frappe Framework, a full-stack web application framework written in Python and JavaScript. This architecture separates ERPNext into distinct layers: the backend handles business logic using Python, while the frontend delivers a responsive user interface through JavaScript and modern web technologies. The system relies on MariaDB for data persistence, Redis for caching and background job queuing, and Node.js for asset compilation and real-time features.

The modular design allows businesses to activate only the features they need. Core modules include Accounting for financial management, CRM for customer relationship tracking, Stock for inventory control, Manufacturing for production planning, and HR for employee management. Unlike competing solutions such as Odoo or SAP Business One, ERPNext offers complete source code access and modification rights, making it highly customizable for specific business requirements.

Organizations across retail, manufacturing, healthcare, education, and services sectors successfully deploy ERPNext to streamline operations. The platform scales from single-user implementations to multi-site deployments serving hundreds of concurrent users, making it versatile enough for startups and established enterprises alike.

Prerequisites and System Requirements

Hardware Requirements

A successful ERPNext installation demands adequate server resources. Minimum specifications include 4GB of RAM, though 8GB is strongly recommended for production environments handling moderate transaction volumes. The system requires at least 40GB of disk space to accommodate the application, database, and generated files. CPU performance directly impacts user experience; a dual-core processor suffices for testing, but production deployments benefit from quad-core processors or better. Solid-state drives (SSDs) significantly improve database query performance and overall system responsiveness.

Software Requirements

This installation requires a fresh Debian 13 server, either a Virtual Private Server (VPS) or dedicated hardware. Root access via SSH or a user account with sudo privileges is mandatory for installing system packages and configuring services. A domain name configured to point to the server’s IP address enables proper ERPNext site creation and SSL certificate installation. Starting with a clean Debian 13 installation prevents conflicts with existing software packages and ensures compatibility.

Knowledge Prerequisites

While this guide provides detailed instructions, basic Linux command-line familiarity helps navigate the terminal environment confidently. Understanding SSH connections for remote server access, basic networking concepts, and text editor usage (nano or vi) proves beneficial throughout the installation process.

Step 1: Initial System Preparation

Begin by connecting to the Debian 13 server via SSH. Update the package repository index and upgrade all installed packages to their latest versions:

apt update && apt upgrade -y

This command ensures the system runs the most recent security patches and bug fixes. Starting with an updated system prevents potential compatibility issues during ERPNext installation. The process may take several minutes depending on the number of packages requiring updates.

Configure the Uncomplicated Firewall (UFW) to protect the server:

apt install ufw -y
ufw allow OpenSSH
ufw enable

These commands install UFW, permit SSH connections to prevent lockout, and activate the firewall. Additional ports will be opened later for web traffic.

Set the correct timezone to ensure accurate timestamps in ERPNext records:

timedatectl set-timezone Asia/Jakarta

Replace “Asia/Jakarta” with the appropriate timezone for the deployment location. Verify the timezone with timedatectl status.

Throughout this guide, commands prefixed with # indicate root user execution, while $ denotes regular user commands.

Step 2: Creating a Dedicated System User

ERPNext requires a dedicated system user for security isolation and proper file permissions. Running the application as root poses significant security risks. Create a new user named “erpnext”:

adduser erpnext

The system prompts for a password. Choose a strong password combining uppercase letters, lowercase letters, numbers, and special characters. Additional user information fields can be left blank or filled according to organizational policies.

Add the erpnext user to the sudo group to enable administrative commands:

usermod -aG sudo erpnext

This grants elevated privileges when needed without requiring constant root access. Switch to the newly created user:

su - erpnext

All subsequent installation steps execute under this user account unless specifically noted. This approach follows security best practices by limiting potential damage from compromised processes.

Step 3: Installing Essential Dependencies

ERPNext depends on numerous system packages and libraries. Install the build tools and essential utilities:

sudo apt install -y git python3-dev python3-setuptools python3-pip python3-venv

Git provides version control for downloading Frappe Framework and ERPNext code. Python development packages enable compilation of Python modules with C extensions. The setuptools and pip packages facilitate Python package management, while venv creates isolated Python environments.

Install Redis, the in-memory data structure store used for caching and background job queuing:

sudo apt install -y redis-server

Verify Redis is running:

sudo systemctl status redis-server

The output should display “active (running)” in green text. Redis significantly improves ERPNext performance by caching frequently accessed data and managing asynchronous task queues.

Install additional required libraries:

sudo apt install -y curl xvfb libfontconfig wkhtmltopdf libssl-dev libffi-dev gcc g++ make

The wkhtmltopdf package generates PDF documents from HTML content, essential for printing invoices, reports, and other documents. The libssl-dev and libffi-dev packages provide cryptographic and foreign function interface capabilities. Compilation tools (gcc, g++, make) build native Python extensions during installation.

Step 4: Installing and Configuring Python

Debian 13 includes Python 3.13 by default, which ERPNext version 15 supports. However, Python 3.13 introduces an “EXTERNALLY-MANAGED” restriction preventing system-wide pip installations. This security feature protects system Python packages from accidental modification.

Verify the Python version:

python3 --version

The output should display “Python 3.13.x”. Check pip installation:

pip3 --version

To work around the EXTERNALLY-MANAGED restriction for Frappe Bench installation, create a pip configuration file:

mkdir -p ~/.config/pip
echo "[global]" > ~/.config/pip/pip.conf
echo "break-system-packages = true" >> ~/.config/pip/pip.conf

This configuration allows pip to install packages system-wide, necessary for the bench command-line tool. In production environments, consider using virtual environments for better isolation, though Frappe Bench manages its own virtual environment for the framework and applications.

Step 5: Installing Node.js, NPM, and Yarn

ERPNext’s frontend requires Node.js for compiling JavaScript and CSS assets. Debian 13 repositories may not include the latest LTS version, so add the NodeSource repository:

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -

Install Node.js and NPM:

sudo apt install -y nodejs

Verify the installations:

node --version
npm --version

Node.js version should be 22.x or later, while NPM should report 10.x or higher. These versions ensure compatibility with ERPNext’s frontend build process and JavaScript dependencies.

Install Yarn globally using NPM:

sudo npm install -g yarn

Yarn provides faster and more reliable package management compared to NPM alone. The global installation makes Yarn available system-wide for all users.

Verify Yarn installation:

yarn --version

Using incompatible Node.js versions causes build failures. Always verify version compatibility with the specific ERPNext release being installed.

Step 6: Installing and Securing MariaDB Server

MariaDB serves as ERPNext’s primary database management system, storing all application data. Install MariaDB from Debian repositories:

sudo apt install -y mariadb-server mariadb-client

Start and enable the MariaDB service:

sudo systemctl start mariadb
sudo systemctl enable mariadb

Verify the service is active:

sudo systemctl status mariadb

Securing MariaDB

Run the security script to harden the installation:

sudo mariadb-secure-installation

The script presents several prompts:

1. Enter current root password (press Enter if none exists)
2. Switch to unix_socket authentication? (Select N)
3. Change the root password? (Select Y and enter a strong password)
4. Remove anonymous users? (Select Y)
5. Disallow root login remotely? (Select Y)
6. Remove test database? (Select Y)
7. Reload privilege tables? (Select Y)

These steps eliminate common security vulnerabilities in default MariaDB installations.

Configuring MariaDB for ERPNext

ERPNext requires specific MariaDB character set and storage engine configurations. Edit the server configuration file:

sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf

Add the following lines under the [mysqld] section:

[mysqld]
innodb-file-format=barracuda
innodb-file-per-table=1
innodb-large-prefix=1
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

These settings enable the Barracuda file format for InnoDB tables, set UTF-8 4-byte character encoding for proper emoji and international character support, and configure proper collation.

Edit the client configuration:

sudo nano /etc/mysql/mariadb.conf.d/50-client.cnf

Add under the [mysql] section:

[mysql]
default-character-set = utf8mb4

Restart MariaDB to apply changes:

sudo systemctl restart mariadb

Incorrect character set configuration causes data corruption when storing special characters or emojis.

Step 7: Installing Nginx Web Server

Nginx acts as a reverse proxy, forwarding HTTP requests to ERPNext’s application server. Install Nginx:

sudo apt install -y nginx

Enable and start the service:

sudo systemctl enable nginx
sudo systemctl start nginx

Edit the main Nginx configuration:

sudo nano /etc/nginx/nginx.conf

Change the user directive from “www-data” to “erpnext”:

user erpnext;

This ensures Nginx can access files owned by the erpnext user. The Frappe Bench setup process later generates site-specific Nginx configurations.

Verify the configuration syntax:

sudo nginx -t

Reload Nginx:

sudo systemctl reload nginx

Open firewall ports for web traffic:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Port 80 handles HTTP traffic, while 443 serves HTTPS connections after SSL certificate installation.

Step 8: Installing Supervisor Process Manager

Supervisor manages ERPNext background processes, automatically restarting them if they crash. Install Supervisor:

sudo apt install -y supervisor

Enable and start the service:

sudo systemctl enable supervisor
sudo systemctl start supervisor

Check the status:

sudo systemctl status supervisor

Supervisor ensures ERPNext workers, schedulers, and background jobs run continuously. The Frappe Bench setup process generates the necessary Supervisor configuration files.

Step 9: Installing Frappe Bench

Frappe Bench provides command-line utilities for managing Frappe Framework installations, creating sites, installing apps, and configuring production environments. Install bench using pip3:

sudo pip3 install frappe-bench

Due to the EXTERNALLY-MANAGED workaround configured earlier, this installation proceeds without errors. Verify the installation:

bench --version

The command should display the bench version number. Locate the bench binary:

which bench

Typically installed to /usr/local/bin/bench, this location should be in the system PATH. Frappe Bench serves as the primary interface for all ERPNext management tasks, from initial setup through daily maintenance operations.

Step 10: Initializing Frappe Framework

Create a new bench directory and initialize the Frappe Framework:

cd ~
bench init frappe-bench --frappe-branch version-15

This command downloads Frappe Framework version 15, creates a Python virtual environment, installs Python dependencies, and sets up the basic directory structure. The process takes several minutes as it downloads and configures numerous packages.

The --frappe-branch version-15 flag specifies Frappe Framework version 15, ensuring compatibility with ERPNext version 15. Using mismatched versions causes installation failures.

Once initialization completes, navigate to the bench directory:

cd frappe-bench

This directory contains several subdirectories:

• apps/ – Frappe applications including framework and ERPNext
• sites/ – Individual site configurations and files
• config/ – System configuration files
• logs/ – Application and error logs
• env/ – Python virtual environment

Understanding this structure helps troubleshoot issues and perform maintenance tasks.

Step 11: Creating an ERPNext Site

ERPNext supports multi-tenancy, allowing multiple sites on a single installation. Create a new site using a domain name:

bench new-site yourdomain.com

Replace “yourdomain.com” with the actual domain name. The system prompts for:

1. MariaDB root password (entered during MariaDB security setup)
2. Administrator password (create a strong password for ERPNext admin user)

The site creation process establishes a new database, installs base Frappe Framework tables, and configures the site directory. Each site maintains its own database, file storage, and configuration.

Enable the scheduler for background jobs:

bench --site yourdomain.com enable-scheduler

The scheduler executes recurring tasks like email sending, report generation, and database cleanup. Disable maintenance mode:

bench --site yourdomain.com set-maintenance-mode off

Maintenance mode prevents user access during administrative tasks. Disabling it allows normal site operation.

Step 12: Installing ERPNext Application

Download the ERPNext application:

bench get-app erpnext --branch version-15

This command clones the ERPNext repository for version 15 into the apps directory. The download includes all ERPNext modules and dependencies. The process may take several minutes depending on internet connection speed.

Install ERPNext to the created site:

bench --site yourdomain.com install-app erpnext

Installation creates database tables for all ERPNext modules, installs default data like countries and currencies, and configures module settings. This process typically requires 5-10 minutes. The terminal displays progress as each module installs.

Optional: Install the payments app for payment gateway integration:

bench get-app payments
bench --site yourdomain.com install-app payments

The payments app enables online payment processing through providers like Stripe, PayPal, and Razorpay.

Step 13: Configuring Production Environment

Development mode runs ERPNext on a built-in server unsuitable for production. Configure Nginx and Supervisor for production deployment.

Setting Up Nginx Configuration

Generate Nginx configuration files:

bench setup nginx

This creates site-specific configuration files in the config directory. Create a symbolic link to enable the configuration:

sudo ln -s /home/erpnext/frappe-bench/config/nginx.conf /etc/nginx/conf.d/frappe-bench.conf

Test Nginx configuration:

sudo nginx -t

If errors appear, review the configuration file for syntax issues.

Setting Up Supervisor Configuration

Generate Supervisor configuration:

bench setup supervisor

Create a symbolic link:

sudo ln -s /home/erpnext/frappe-bench/config/supervisor.conf /etc/supervisor/conf.d/frappe-bench.conf

Restarting Services

Restart Nginx:

sudo systemctl restart nginx

Reload Supervisor configuration:

sudo supervisorctl reread
sudo supervisorctl update

Start all ERPNext processes:

sudo supervisorctl start all

Check process status:

sudo supervisorctl status

All processes should display “RUNNING” status. Common processes include frappe-bench-web, frappe-bench-worker, frappe-bench-schedule, and frappe-bench-redis. If any processes show “FATAL” or “STOPPED”, check logs in the frappe-bench/logs directory.

Step 14: Accessing ERPNext Web Interface

Open a web browser and navigate to the configured domain name (http://yourdomain.com). The ERPNext login page displays with fields for username and password.

Enter “Administrator” as the username and the password created during site setup. The first login triggers the Setup Wizard, which guides through initial configuration:

1. Language Selection – Choose the primary language for the ERPNext interface
2. Region Settings – Select country and timezone for proper date/time formatting
3. Currency Settings – Set default currency for financial transactions
4. Company Information – Enter organization name, abbreviation, and fiscal year details
5. User Details – Create the first user account with appropriate role assignments
6. Domain Selection – Choose business domain (manufacturing, retail, services, etc.)

Completing the wizard redirects to the ERPNext dashboard, displaying the main interface with module icons, quick access shortcuts, and activity feeds. The clean, modern interface provides intuitive navigation through ERPNext’s comprehensive feature set.

Step 15: Post-Installation Configuration

Security Hardening

Install and configure fail2ban to prevent brute force attacks:

sudo apt install -y fail2ban
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

Create a jail configuration for ERPNext login attempts. Configure automatic security updates to receive critical patches promptly.

SSL Certificate Installation

Install Certbot for Let’s Encrypt SSL certificates:

sudo apt install -y certbot python3-certbot-nginx

Obtain and install a certificate:

sudo certbot --nginx -d yourdomain.com

Certbot automatically configures Nginx for HTTPS and sets up automatic renewal. SSL encryption protects sensitive business data transmitted between browsers and the server.

Performance Optimization

Tune MariaDB for better performance by adjusting the InnoDB buffer pool size in /etc/mysql/mariadb.conf.d/50-server.cnf:

innodb_buffer_pool_size = 2G

Set this to 50-70% of available RAM for dedicated database servers. Configure Redis maxmemory and eviction policies in /etc/redis/redis.conf:

maxmemory 512mb
maxmemory-policy allkeys-lru

These settings prevent Redis from consuming excessive memory.

Backup Strategy

Implement automated backups using the bench backup command:

bench --site yourdomain.com backup

This creates database and file backups in the site’s backup directory. Schedule daily backups using cron:

0 2 * * * cd /home/erpnext/frappe-bench && bench --site yourdomain.com backup

Store backups on external storage or cloud services for disaster recovery.

Initial ERPNext Configuration

Configure company details completely, including address, tax registration numbers, and contact information. Set up the chart of accounts matching the organization’s accounting structure. Create user accounts with appropriate role-based permissions limiting access to sensitive modules. Customize print formats for invoices, quotations, and other documents to match branding guidelines.

Troubleshooting Common Issues

Python 3.13 EXTERNALLY-MANAGED Error

If encountering “error: externally-managed-environment” during bench installation, verify the pip configuration file exists with the break-system-packages directive. Alternatively, use the --break-system-packages flag directly:

sudo pip3 install frappe-bench --break-system-packages

Node.js Version Compatibility

ERPNext version 15 requires Node.js 18.x or higher. If experiencing JavaScript compilation errors, verify Node.js version and upgrade if necessary using NodeSource repositories.

MariaDB Connection Errors

Database connection failures often stem from incorrect credentials or character set issues. Verify MariaDB root password, check that utf8mb4 character set is configured properly, and ensure MariaDB service is running.

Permission Denied Errors

File permission problems occur when services run under incorrect user accounts. Ensure the erpnext user owns all files in frappe-bench directory:

sudo chown -R erpnext:erpnext /home/erpnext/frappe-bench

Verify Nginx runs as the erpnext user in /etc/nginx/nginx.conf.

Supervisor Process Failures

If Supervisor shows processes in FATAL state, examine log files in frappe-bench/logs/ for specific error messages. Common causes include port conflicts, insufficient memory, or missing dependencies. Restart failed processes after resolving issues:

sudo supervisorctl restart all

Slow Performance

Performance degradation typically results from inadequate resources, inefficient queries, or lack of caching. Monitor system resources with htop or top commands. Review slow query logs in MariaDB. Ensure Redis cache operates correctly. Consider upgrading server specifications for high-traffic deployments.

Best Practices and Recommendations

Establish a regular backup schedule with both on-site and off-site storage. Test backup restoration procedures periodically to ensure recoverability. Document all customizations, configurations, and workflow modifications for team reference and disaster recovery.

Keep ERPNext and its dependencies updated with the latest stable releases. Subscribe to ERPNext security announcements and apply patches promptly. Test updates in a staging environment before deploying to production.

Monitor system logs regularly using tools like journalctl and custom log analysis scripts. Set up automated alerts for critical errors, disk space issues, and service failures. Implement system monitoring with Prometheus, Grafana, or similar solutions.

Plan capacity upgrades before reaching resource limits. Monitor database growth, user counts, and transaction volumes to predict scaling needs. ERPNext scales both vertically (larger servers) and horizontally (multiple servers with load balancing).

Maintain comprehensive documentation of organizational processes, custom reports, and business logic encoded in ERPNext. Train users thoroughly on relevant modules to maximize system adoption and efficiency. Establish internal support channels for user questions and issues.

Congratulations! You have successfully installed ERPNext. Thanks for using this tutorial for installing ERPNext open-source ERP software on Debian 13 “Trixie” system. For additional help or useful information, we recommend you check the official ERPNext website.