ERPNext Setup on Ubuntu 22.04 – From Zero to Hero!

📑 Table of Contents

1. 🌟 Introduction: Why ERPNext?

2. 🎯 Aim of this Blog

3. 🛠️ Prerequisites Before You Begin

4. ⚙️ Step 1: Server Setup – Preparing Ubuntu for ERPNext

5. 📦 Step 2: Install Required Packages

6. 🗄️ Step 3: Configure MySQL Server

7. 🔧 Step 4: Install CURL, Node.js, NPM, and Yarn

8. 🏗️ Step 5: Install Frappe Bench Framework

9. 🚀 Step 6: Install ERPNext and Other Applications

10. ✅ Final Verification and Testing Your Setup

11. 📌 Conclusion: Running ERPNext Smoothly

🌟 Introduction : Why ERPNext?

Running a business requires managing multiple operations finance, sales, HR, payroll, CRM, projects, and more. Instead of juggling multiple tools, wouldn’t it be better to have one platform for everything? That’s exactly what ERPNext delivers.

ERPNext is an open-source ERP solution designed to simplify and automate business processes. From startups to enterprises, it’s trusted worldwide for being cost-effective, flexible, and scalable. Unlike other ERP tools that demand heavy licensing costs, ERPNext offers a free and community-driven platform that anyone can install and use.This blog is your complete, beginner-friendly guide to installing ERPNext on Ubuntu 22.04 LTS.

🎯 Aim of this Blog

The main objective of this guide is to help you:

• ✅ Understand ERPNext installation requirements.

• ✅ Learn server setup and dependency installation.

• ✅ Configure and install ERPNext with Frappe framework.

• ✅ Explore add-on modules like HR, Payroll, Sales, and CRM.

By the end, you’ll have a fully functional ERPNext system running on your local machine.

🛠️ Prerequisites Before You Begin

Before we start the installation, make sure your system meets the minimum requirements:

🔹 Operating System

• Ubuntu 22.04 LTS (64-bit)

🔹 Minimum Hardware Requirements

• CPU: 2 cores

• RAM: 2 GB

• Storage: 15 GB free disk space

(Tip: For smoother performance, 4 GB RAM and 2+ CPUs are recommended.)

🔹 Setup Environment

• Perform the installation on a local machine for practice/testing.

• Ensure you have basic Linux command knowledge (updating system, installing packages, using terminal).

⚙️ Step 1: Server Setup – Preparing Ubuntu

Before we start installing ERPNext, let’s make sure our Ubuntu 22.04 server is ready.

🔹 Update & Upgrade Packages

Keep the system up to date:

sudo apt update && sudo apt upgrade -y

🔹 Set Timezone

Correct timezone ensures accuracy in reports, HR, and payroll:

sudo timedatectl set-timezone Asia/Kolkata

🔹 Install Basic Tools

Essential utilities for smooth installation:

sudo apt install git curl wget htop nano unzip -y

✅ That’s it! Your server is now ready to proceed with ERPNext installation.

📦 Step 2: Install Required Packages

In this step, we install the essential tools for Python, create swap memory for smooth performance, and set up MariaDB (MySQL alternative) for database support.

---

🐍 Install Python + Build Tools

sudo apt -y install python3 python3-pip python3-venv python3-dev build-essential libffi-dev libssl-dev

🔎 Explanation:

• python3 → Installs the Python 3 interpreter.

• python3-pip → Python package manager (used to install libraries).

• python3-venv → For creating isolated virtual environments.

• python3-dev → Development headers required for compiling Python extensions.

• build-essential → Provides compiler tools like gcc and make.

• libffi-dev & libssl-dev → Required for cryptography and secure connections.

👉 These dependencies are necessary for ERPNext/Bench to work properly.

---

🧠 Create & Enable Swap Memory

sudo fallocate -l 2G /swapfile    # Create a 2GB swap file
sudo chmod 600 /swapfile          # Set correct permissions
sudo mkswap /swapfile             # Format the swap file
sudo swapon /swapfile             # Enable swap
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab   # Make swap permanent after reboot

🔎 Explanation:

• Swap memory acts as virtual RAM using disk space.

• If the system runs out of physical RAM, swap ensures processes don’t crash.

• Here, we created a 2GB swap file to handle heavy package installations and Python compilations smoothly.

---

🗄️ Install MariaDB (MySQL Server)

sudo apt -y install mariadb-server mariadb-client

🔎 Explanation:

• mariadb-server → Installs the database engine (where ERPNext stores data).

• mariadb-client → Provides tools to interact with the database.

👉 MariaDB is a drop-in replacement for MySQL — it uses the same commands but is faster and open-source.

---

🗄️ Step 3: Configure MySQL Server

Now, let’s secure the MariaDB server.

sudo mysql_secure_installation

🔎 Explanation:
This is an interactive script that asks security-related questions:

1. Set root password → Protects the database root user with a password.

2. Remove anonymous users → Deletes default anonymous accounts.

3. Disallow remote root login → Ensures root can only log in from localhost.

4. Remove test database → Deletes the unnecessary test DB.

👉 These steps make MariaDB secure and production-ready.

🔑 Understanding the bind-address in MariaDB for ERPNext

When setting up ERPNext on Ubuntu with MariaDB, one important configuration line you might have noticed in the erpnext.cnf file is:

bind-address = 127.0.0.1

But what does this mean, and why do we use it? 🤔

---

🌐 What is bind-address?

The bind-address tells MariaDB which network interface (IP address) it should listen to for incoming connections.

• 127.0.0.1 → This is the loopback address (localhost). It means MariaDB will only accept connections from the same machine where it is installed.

• Any other IP (like 0.0.0.0 or server’s public IP) → MariaDB would listen to requests from outside machines too.

---

🔒 Why use 127.0.0.1 for ERPNext?

For most ERPNext installations:
✅ ERPNext and MariaDB run on the same server.
✅ We don’t need external machines to connect directly to MariaDB.
✅ It provides better security, as no one from outside the server can attempt to connect to the database.

This is why:

bind-address = 127.0.0.1

is the safest choice for local or single-server ERPNext setups.

⚡ Step 4: Install Redis, Node.js, Yarn & Frappe Bench

In this step, we will install all the required tools to run ERPNext efficiently.

---

🛠️ 4.1 Install Redis & wkhtmltopdf

1️⃣ Install Redis & wkhtmltopdf:

sudo apt -y install redis-server wkhtmltopdf

👉 redis-server: Used for caching and background task queues.
👉 wkhtmltopdf: Helps ERPNext generate PDF reports (Invoices, Quotations, etc.).

2️⃣ Enable Redis to start on boot:

sudo systemctl enable redis-server

👉 Makes sure Redis automatically starts when the server reboots.

3️⃣ Start Redis immediately:

sudo systemctl start redis-server

👉 Runs Redis service right now without waiting for reboot.\

4️⃣ Test Redis is working:

redis-cli ping

👉 If Redis is active, you will see PONG ✅.

---

⚙️ 4.2 Install Node.js

1️⃣ Add Node.js 18.x repository:

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

👉 Downloads & configures Node.js LTS (18.x) setup for Ubuntu.

2️⃣ Install Node.js:

sudo apt -y install nodejs

👉 Installs both Node.js (runtime) and npm (package manager).

📦 4.3 Install Yarn

1️⃣ Install Yarn globally:

sudo npm install -g yarn

👉 Yarn is a faster package manager used by ERPNext frontend for handling JavaScript libraries.

2️⃣ Check Yarn version:

yarn -v

👉 Confirms Yarn is installed successfully.

3️⃣ Check Node.js version:

node -v

👉 Confirms Node.js installed properly.

4️⃣ Check npm version:

npm -v

👉 Confirms npm (Node package manager) is working.

🚀 4.4 Install Frappe Bench

1️⃣ Install pipx (required for managing Python apps safely):

sudo apt -y install pipx

👉 Installs pipx, which isolates Python-based applications.

2️⃣ Add pipx to system PATH:

pipx ensurepath

👉 Ensures pipx commands can run globally from terminal.

3️⃣ Install Frappe Bench:

pipx install frappe-bench

👉 Installs the bench tool, used to create and manage ERPNext projects/sites.

4️⃣ Verify Bench installation:

bench --version

👉 Confirms that Bench is installed correctly.

✨ ✅ At this point, Redis, Node.js, Yarn, and Frappe Bench are all set up!

🏗️ Step 5: Installing Frappe Bench Framework

The Frappe Bench is the backbone of ERPNext. It helps you create, manage, and run multiple ERPNext sites with ease 🚀. Let’s set it up!

---

⚡ 1. Create a Frappe Directory

mkdir -p ~/frappe && cd ~/frappe

🔹 mkdir -p ~/frappe → Creates a new folder called frappe inside your home directory.
🔹 cd ~/frappe → Immediately moves you inside that folder.

👉 This ensures we have a clean space where all ERPNext files will be stored 📂.

---

⚡ 2. Initialize Bench with Frappe v15

bench init --frappe-branch version-15 frappe-bench

🔹 bench init → Starts the setup of a new Bench environment.
🔹 --frappe-branch version-15 → Installs the latest stable Frappe v15.
🔹 frappe-bench → Name of the folder where the new Bench environment will be created.

👉 After this, a new directory frappe-bench is created which contains all necessary files ⚙️.

---

⚡ 3. Move into Bench Directory

cd frappe-bench

🔹 Switches into the frappe-bench folder created in the previous step.
👉 From here, you can start creating ERPNext sites and apps 🎯.

✨ Step 6: Installing ERPNext and Applications

Once your Frappe Framework is ready, the next move is to bring ERPNext into action. This step will set up ERPNext inside your local environment 🚀.

---

🖥️ 1. Create a New Site

bench new-site site1.local

🔹 Creates a fresh site named site1.local.
🔹 It will ask for:

• MySQL root password 🔑

• Administrator password (used later for ERPNext login)

👉 Think of this as preparing an empty house 🏠 where ERPNext will live.

---

📥 2. Download ERPNext App

bench get-app erpnext --branch version-15

🔹 Fetches ERPNext source code from GitHub.
🔹 --branch version-15 ensures you install the latest stable ERPNext (v15).

👉 Like bringing ERPNext package 📦 into your system.

---

🔗 3. Install ERPNext on Your Site

bench --site site1.local install-app erpnext

🔹 Installs ERPNext inside your site.
🔹 Now, site1.local is fully powered by ERPNext.

👉 Imagine you just plugged ERPNext’s engine 🚂 into your site.

---

🎨 4. Build ERPNext Assets

bench build --app erpnext

🔹 Compiles JS, CSS, and frontend files.
🔹 Without this, your ERPNext dashboard may look broken.

👉 This step decorates the house 🏡✨, making ERPNext’s UI ready.

---

⚡ 5. Install Honcho (Process Manager)

pip install honcho
honcho --version

🔹 Honcho helps run multiple services (Frappe, Redis, Workers) together.
🔹 First command installs it, second confirms the version.

👉 Think of Honcho as your site manager 👷, keeping everything running smoothly.

✅ Final Verification and Testing Your Setup

▶️ Start ERPNext and Access on Localhost

Once ERPNext is installed, it’s time to bring it to life! 🚀

🔹 Step 1: Go to your bench folder

cd ~/frappe-bench

🔹 Step 2: Start ERPNext services

bench start

This command will launch the web server, scheduler, workers, and all background services required for ERPNext.

🔹 Step 3: Open ERPNext in your browser

Now visit:

http://site1.local:8000

(If site1.local doesn’t work, try http://localhost:8000)

✨ And boom 💥 — your ERPNext dashboard will appear, ready for you to explore modules like HR, Sales, CRM, Accounting, Inventory, and more! 🎯

🎉 After installing ERPNext, complete the Setup Wizard by creating your admin account and entering your company details. Once done, you’ll be redirected straight to the ERPNext dashboard, ready to explore all modules. 🚀

⚠️ Notice
If you don’t see modules like HR, Sales, CRM, Accounting, or Tools on your ERPNext dashboard after installation, don’t worry!

👉 Simply use the Search Bar (Ctrl + G) at the top and type the module name (e.g., HR or Sales). Once opened, you can pin or add them to your sidebar/dashboard.

This happens because ERPNext hides some modules by default — but they are all available and just one search away. ✅

✅ Conclusion
You’ve now completed the full journey from setting up the server to launching ERPNext on your browser. 🎯 With modules like HR, Sales, CRM, Accounting, and Inventory, your business is ready to streamline operations on a modern open-source ERP system. This is just the beginning explore, customize, and make ERPNext truly yours! 🚀

👨‍💻 About the Author

This project is a deep dive into the ERPNext ecosystem, designed to strengthen my foundation in enterprise resource planning, business automation, and modular integration using open-source technology.

This series isn’t just about installing ERPNext; it’s about mastering the core modules that power modern business management from HR and Sales to Accounting, Inventory, and CRM. 🚀

---

📬 Let's Stay Connected

• 📧 Email: gujjarapurv181@gmail.com

• 🐙 GitHub: github.com/ApurvGujjar07

• 💼 LinkedIn: linkedin.com/in/apurv-gujjar

✨ Final Note
This blog is a reflection of my personal journey and learning efforts. I have written and shaped it with my own understanding and dedication. Still, perfection is a continuous process so if you find any mistakes, missing points, or areas of improvement, feel free to share your suggestions in the comments. Your feedback will not only help me improve this work but will also add more value to everyone who reads it. 🚀

Thank you for taking the time to read! 🙌