DEV Community

erpgenex micro
erpgenex micro

Posted on

ERPGENEX Free Open-Source ERP Built on Frappe Framework

#linux #opensource #python #tutorial

Full Install Guide (Ubuntu Server Frappe/Bench omnexa_core)

This guide walks you through a clean install on Ubuntu Server, from OS prep to a running Frappe site with omnexa_core.

Note: On develop, omnexa_core can auto-fetch required ErpGenEx apps via bench get-app before completing site installation (when missing from the bench).

1) Server prerequisites

  • Ubuntu 24.04 LTS (recommended) or Ubuntu 22.04 LTS
  • A non-root Linux user (example: frappeuser) with sudo
  • DNS / domain name (optional at first)
  • Open ports: 22 (SSH) + 80/443 (Nginx) or 8000 (dev)

2) Update the OS and install base tools 

sudo apt update && sudo apt -y upgrade
sudo apt -y install git curl wget vim software-properties-common ca-certificates
Enter fullscreen mode Exit fullscreen mode

3) Install dependencies (Python / Node / Yarn / Redis / MariaDB)

3.1 Python build deps 

sudo apt -y install python3-dev python3-pip python3-venv build-essential
Enter fullscreen mode Exit fullscreen mode

3.2 MariaDB and Redis 

sudo apt -y install mariadb-server mariadb-client redis-server
sudo systemctl enable --now mariadb redis-server
Enter fullscreen mode Exit fullscreen mode

3.3 Node.js and Yarn

Frappe v15 typically works well with Node 18.

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt -y install nodejs
sudo npm install -g yarn
Enter fullscreen mode Exit fullscreen mode

3.4 wkhtmltopdf (PDF printing) 

sudo apt -y install xvfb libfontconfig wkhtmltopdf
Enter fullscreen mode Exit fullscreen mode

3.5 MariaDB configuration for Frappe (UTF8MB4) 

sudo mysql_secure_installation
Enter fullscreen mode Exit fullscreen mode

Then add UTF8MB4 defaults:

sudo tee /etc/mysql/mariadb.conf.d/99-frappe.cnf > /dev/null <<'EOF'
[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

[mysql]
default-character-set = utf8mb4
EOF

sudo systemctl restart mariadb
Enter fullscreen mode Exit fullscreen mode

4) Install Bench and initialize a new bench

4.1 Install bench 

sudo pip3 install frappe-bench
Enter fullscreen mode Exit fullscreen mode

4.2 Initialize bench 

bench init frappe-bench --frappe-branch version-15
cd frappe-bench
Enter fullscreen mode Exit fullscreen mode

If you hit permissions issues, ensure the same Linux user (e.g. frappeuser) owns and operates the bench folder.

5) Create a new site 

bench new-site erpgenex.local.site
Enter fullscreen mode Exit fullscreen mode

5.1 (Optional) Set the default site 

bench use erpgenex.local.site
Enter fullscreen mode Exit fullscreen mode

6) Fetch omnexa_core (GitHub) and install it

6.1 Fetch the app 

bench get-app https://github.com/ErpGenex/omnexa_core.git --branch develop
Enter fullscreen mode Exit fullscreen mode

6.2 Install on the site 

bench --site erpgenex.local.site install-app omnexa_core
Enter fullscreen mode Exit fullscreen mode

6.3 Auto-fetch required apps (important)

During omnexa_core install, if required stack apps are missing from the bench apps/ directory, omnexa_core will attempt to:

  • run bench get-app ... --skip-assets for each missing required app
  • run bench setup requirements
  • then continue the site installation

Feature controls:

# Disable auto-fetch
export OMNEXA_AUTO_GET_APPS=0

# Override org/branch (if needed)
export ERPGENEX_GITHUB_ORG=ErpGenex
export OMNEXA_APPS_BRANCH=develop
Enter fullscreen mode Exit fullscreen mode

7) Run the stack

7.1 Development mode (quick) 

bench start
Enter fullscreen mode Exit fullscreen mode

Open:

  • http://<server-ip>:8000

7.2 Production (short version)

Production setup depends on Nginx + Supervisor/Systemd on your server. A quick start is:

sudo bench setup production frappeuser
Enter fullscreen mode Exit fullscreen mode

Then access via:

  • http://<server-ip> (through Nginx)

8) Troubleshooting

8.1 Error: No module named '<app>'

This means the app source isn't present under apps/ or isn't installed into the bench venv.

bench get-app https://github.com/ErpGenex/<app>.git --branch develop
bench setup requirements
Enter fullscreen mode Exit fullscreen mode

8.2 MariaDB “Access denied” during migrate/install

Check:

  • sudo systemctl status mariadb
  • your site database settings in sites/<site>/site_config.json

8.3 bench drop-site prompts for MariaDB root password

Use non-interactive flags:

bench drop-site erpgenex.local.site --no-backup --force --root-login root --root-password 'YOUR_MYSQL_ROOT_PASSWORD'
Enter fullscreen mode Exit fullscreen mode

9) Quick post-install checks 

bench --site erpgenex.local.site list-apps
bench --site erpgenex.local.site migrate
bench build
Enter fullscreen mode Exit fullscreen mode

Top comments (0)