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

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

3.2 MariaDB and Redis

sudo apt -y install mariadb-server mariadb-client redis-server
sudo systemctl enable --now mariadb redis-server

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

3.4 wkhtmltopdf (PDF printing)

sudo apt -y install xvfb libfontconfig wkhtmltopdf

3.5 MariaDB configuration for Frappe (UTF8MB4)

sudo mysql_secure_installation

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

4) Install Bench and initialize a new bench

4.1 Install bench

sudo pip3 install frappe-bench

4.2 Initialize bench

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

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

5.1 (Optional) Set the default site

bench use erpgenex.local.site

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

6.2 Install on the site

bench --site erpgenex.local.site install-app omnexa_core

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

7) Run the stack

7.1 Development mode (quick)

bench start

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

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

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'

9) Quick post-install checks

bench --site erpgenex.local.site list-apps
bench --site erpgenex.local.site migrate
bench build