Aug 20, 2024 β€’ 3 min read

ERPNext: A Beginner-Friendly Guide to Self-Hosting

ERPNext: A Beginner-Friendly Guide to Self-Hosting

ERPNext is a powerful, open-source enterprise resource planning (ERP) platform designed for businesses of all sizes. It offers a wide range of modular features, from inventory and finance to CRM and HR, making it highly versatile. Self-hosting ERPNext gives users full control over their data, advanced customization options, and the ability to tailor the system to specific business needs. This guide provides a complete walkthrough for deploying, configuring, and managing ERPNext, covering installation, reverse proxy setup, backups, upgrades, and more.

Installing ERPNext

πŸ“¦ Docker/Docker Compose Setup

ERPNext supports containerized deployment via Docker, making installation faster and more consistent across environments. Below is an example docker-compose.yml file and the steps to deploy ERPNext via Docker Compose.

Create a docker-compose.yml file:


version: '3.7'

services:

erpnext:

image: frappe/erpnext:version-13

container_name: erpnext

restart: always

ports:

- "8080:80"

environment:

- MYSQL_ROOT_PASSWORD=strongpassword

- ERPNEXT_DATABASE_HOST=db

- ERPNEXT_DATABASE_USER=root

- ERPNEXT_DATABASE_PASSWORD=strongpassword

volumes:

- ./frappe-bench-sites:/home/frappe/frappe-bench/sites

db:

image: mariadb:10.3

container_name: erpnext-db

restart: always

environment:

- MYSQL_ROOT_PASSWORD=strongpassword

volumes:

- ./mysql-data:/var/lib/mysql

Deploy ERPNext using Docker Compose:


git clone https://github.com/frappe/frappe_docker.git

cd frappe_docker

## Start the containers

docker-compose up -d

## Check the status of running containers

docker ps

You can now access ERPNext in your browser on http://<your-server-ip>:8080.

πŸš€ Manual Installation

Manual installation allows for greater flexibility and is ideal for system administrators who prefer to fine-tune their environments.

Install dependencies:


sudo apt update

sudo apt install python3-dev python3-setuptools python3-pip mariadb-server redis-server nginx curl

Install ERPNext and bench CLI:


## Install Frappe Bench

pip3 install frappe-bench

bench init erpnext-bench --frappe-branch version-13

cd erpnext-bench

## Create a new site

bench new-site erp.mydomain.com

## Get ERPNext app

bench get-app erpnext --branch version-13

## Install ERPNext on the site

bench --site erp.mydomain.com install-app erpnext

## Start the development server

bench start

Configuring Nginx as a Reverse Proxy

🌐 Nginx Configuration

Setting up Nginx as a reverse proxy ensures better performance and security when serving ERPNext.

Create an Nginx server block:


server {

listen 80;

server_name erp.mydomain.com;

location / {

proxy_pass http://localhost:8000; # ERPNext default port

proxy_set_header Host $host;

proxy_set_header X-Real-IP $remote_addr;

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

}

}

Apply the configuration:


## Copy the configuration to Nginx

sudo nano /etc/nginx/sites-available/erpnext

sudo ln -s /etc/nginx/sites-available/erpnext /etc/nginx/sites-enabled/

## Test and reload Nginx

sudo nginx -t

sudo systemctl reload nginx

πŸ”’ SSL/TLS Setup

Secure your ERPNext instance using Let's Encrypt.

Install Certbot and obtain a certificate:


sudo apt install certbot python3-certbot-nginx

sudo certbot --nginx -d erp.mydomain.com

Automate certificate renewal:


sudo crontab -e

## Add the following line to renew certificates automatically

0 3 * * * certbot renew --quiet

Logging and Debugging ERPNext

πŸ—ƒοΈ Enabling Debug Logs

Enable debug-level logging to troubleshoot issues.

Update common_site_config.json:


nano ~/frappe-bench/sites/common_site_config.json

Add or update:


"logging_level": "DEBUG"

Restart ERPNext:


bench restart

πŸ“„ Viewing Logs

Access logs to monitor ERPNext activity.

View logs in Docker:


docker logs erpnext

Check log files manually:


cat ~/frappe-bench/logs/web.log

cat ~/frappe-bench/logs/worker.error.log

Backup and Restore

πŸ—‚οΈ File-Based Backups

Backup your ERPNext configuration and data files.

Create a backup of configuration files:


tar -cvzf erpnext-config-backup.tar.gz ~/frappe-bench/sites

πŸ”„ Database Backups

Regularly back up the database to ensure data safety.

Backup the MariaDB database:


mysqldump -u root -p erpnext_db > erpnext_db_backup.sql

Restore the database:


mysql -u root -p erpnext_db < erpnext_db_backup.sql

πŸ“… Automated Backup Scripts

Automate backups with cron jobs.

Create a backup script (backup.sh):


#!/bin/bash

DATE=$(date +%F)

BACKUP_DIR="/backups"

mkdir -p $BACKUP_DIR

mysqldump -u root -pYOUR_PASSWORD erpnext_db > $BACKUP_DIR/erpnext_db_$DATE.sql

tar -cvzf $BACKUP_DIR/erpnext_files_$DATE.tar.gz ~/frappe-bench/sites

Schedule the script:


crontab -e

## Add the following line to run daily at midnight

0 0 * * * /path/to/backup.sh

Updating and Upgrading ERPNext

⬆️ Updating Docker Images

Keep your ERPNext installation up-to-date by upgrading Docker images.

Pull the latest image and restart containers:


docker-compose pull

docker-compose up -d

πŸ› οΈ Manual Updates

For manual installations, update ERPNext via the bench CLI.

Update the application:


cd ~/frappe-bench

bench update

Leveraging ERPNext’s Unique Features

πŸ”§ Enabling APIs

ERPNext exposes RESTful APIs for integration with other systems.

Enable API access:

  1. Go to ERPNext > Integrations > API Access.

  2. Generate an API key and secret.

Use the API with cURL:


curl -X GET https://erp.mydomain.com/api/resource/Item \

-H "Authorization: token <api_key>:<api_secret>"

🌟 Advanced Configurations

Enable advanced features like custom scripts and integrations.

Add a custom script:


cd ~/frappe-bench

bench console


frappe.get_doc({

'doctype': 'Custom Script',

'script': 'console.log("Custom ERPNext script active!");',

'dt': 'Sales Invoice'

}).insert()

Wrapping Up

This guide covered the essentials for deploying, configuring, and managing ERPNext on your own infrastructure. From installation to backups and API integrations, ERPNext offers unparalleled flexibility and control for businesses. Start implementing these steps to unlock ERPNext’s full potential while enjoying the benefits of self-hosting!

Great! You’ve successfully signed up.
Welcome back! You've successfully signed in.
You've successfully subscribed to Selfhosted Ninja.
Your link has expired.
Success! Check your email for magic link to sign-in.
Success! Your billing info has been updated.
Your billing was not updated.