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:
-
Go to ERPNext > Integrations > API Access.
-
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!
