Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsTo install ERPNext on an Ubuntu VPS, first choose a compatible Frappe/ERPNext release, then install its matching database, language runtimes, Node.js tooling, Redis or Valkey, and build utilities. Use Bench to initialize the framework, create a site, download ERPNext, and install the app. A production deployment additionally needs Supervisor to keep workers alive and Nginx to serve static files and proxy requests. The current Frappe documentation recommends Ubuntu 24.04 or newer; older Ubuntu releases can fail because package versions no longer match the supported matrix.
Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.
Choose the ERPNext release before installing anything
ERPNext is installed on top of the Frappe Framework, and every major branch has a dependency matrix. Do not begin with a generic tutorial and decide the version later. Pin the Frappe and ERPNext branches first, then install the versions required by that branch.
As an Amazon Associate I earn from qualifying purchases.
Recommended Free Tools
Frappe’s current installation guidance says you should run Debian 13 or newer or Ubuntu 24.04 or newer; otherwise, some packages may not work. This recommendation can differ from older ERPNext v14 or v15 tutorials, so mixing an old operating-system guide with current dependency commands is a common cause of failed installations.
| Frappe branch | MariaDB | Python | Node.js | Redis or Valkey | Yarn | pip | PDF engine |
|---|---|---|---|---|---|---|---|
| v14/v15 | 10.6.6 or newer | 3.10 or newer | 18 or newer | 6 | 1.12 or newer | 20 or newer | wkhtmltopdf is required |
| v16/develop | 11.8 | 3.14 | 24 | 6 or newer | 1.22 or newer | 25.3 or newer | Bench downloads Chromium; wkhtmltopdf is no longer required |
Use the table as a compatibility check, not as permission to combine arbitrary versions. For example, installing Node.js 24 while following a v14 guide can produce a different failure than installing the Node.js 18 expected by that branch. Keep the Frappe framework branch and ERPNext branch aligned.
Decide whether a VPS is the right production model
A host-based Bench installation gives you direct control over the operating system and every service. It also makes you responsible for MariaDB, Redis or Valkey, Nginx, Supervisor, firewalls, updates, backups, TLS certificates, logs, and recovery testing.
Frappe documents the host-based Bench procedure, but its setup-production guidance warns that installing on bare-metal servers is not recommended and identifies Docker images as the preferred production approach. A conventional VPS is still useful for a controlled self-managed deployment, but you should make that trade-off deliberately.
| Deployment choice | Version and process control | Backups, TLS and monitoring | Operational responsibility |
|---|---|---|---|
| Bench directly on Ubuntu | You pin branches and run Bench commands on the host. | You configure and test backups, certificates, logs and monitoring yourself. | You administer the operating system and every ERPNext service. |
| Docker images | Images provide a repeatable application environment and an explicit upgrade path. | You still need a backup and restore plan, but service boundaries are clearer. | You operate the container stack; Frappe identifies this as the recommended production approach in its setup-production warning. |
| Managed ERPNext hosting | The provider normally handles the application stack and release mechanics. | Confirm who owns backups, restore tests, TLS renewal and monitoring before signing up. | The provider carries more of the routine administration, while you remain responsible for application data and acceptance testing. |
This article follows the documented host-based Bench path. If you do not want to maintain system services, choose a supported container or managed model before creating a production site rather than migrating after an outage.
Prepare the Ubuntu VPS
Use an administrative account, not a permanent root shell
Create a normal user with sudo access and connect over SSH. Reserve root for commands that genuinely require it. This keeps Bench files, SSH keys and application logs owned by the account that runs Bench instead of by root, which avoids permission failures later.
Update the operating system and set a hostname
sudo apt update
sudo apt upgrade -y
hostnamectlSet a stable fully qualified hostname before production configuration. If the site will use a domain, create an A or AAAA record pointing to the VPS address. DNS must resolve to the server before you test the final Nginx virtual host or request a TLS certificate.
Size for workload, not an invented minimum
No authoritative source provides a universal CPU, RAM, disk or installation-time minimum for ERPNext. Size the VPS for the number of users, concurrent background workers, report and PDF workload, database growth, file attachments and the retention period for backups. Leave headroom for migrations and asset builds, which can require more resources than normal browsing.
Free tools Windows power users keep installed
One-click scans. No signup required.
- Estimate peak concurrent users rather than total accounts.
- Include database growth and private/public file storage in disk planning.
- Reserve capacity for scheduled jobs, email queues, imports and PDF generation.
- Keep backups off the VPS so a disk failure does not destroy both data and recovery copies.
Install the base services and build tools
Install Git, MariaDB server and client packages, the MariaDB development libraries, Redis, cron, compiler/build tools and the utilities required by the selected branch. A typical starting command is:
sudo apt install -y git mariadb-server mariadb-client libmariadb-dev redis-server cron curl build-essential pkg-configPackage names can vary slightly between Ubuntu releases. If apt proposes a MariaDB version below the matrix for your branch, stop and select a compatible repository or a different ERPNext branch; do not force the installation with mismatched database packages.
Secure MariaDB
If package installation did not run the hardening wizard, execute:
sudo mariadb-secure-installationFollow the prompts to remove anonymous accounts, prevent remote root login and remove the test database. Keep the database reachable locally from the Bench host unless your architecture explicitly requires a separate database server.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Install the language and JavaScript runtimes
Python and pip
Use the Python version required by your selected branch: Python 3.10 or newer for v14/v15, and Python 3.14 for v16/develop according to the current matrix. Verify both the interpreter and pip before initializing Bench:
python3 --version
python3 -m pip --versionDo not silently substitute the Ubuntu system Python if it is outside the supported range. Bench creates isolated environments, but it still needs a compatible interpreter to build the framework and its dependencies.
Node.js and Yarn
Frappe’s current instructions install Node.js through nvm. Install nvm using its current official installer, open a new shell, and select the branch-appropriate Node.js release:
nvm install 18
nvm alias default 18
node --version
npm --versionUse Node.js 24 for v16/develop instead. Install Yarn at least 1.12 for v14/v15 or at least 1.22 for v16/develop, then verify it:
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteyarn --versionThe number in the command is an example for v14/v15. Replace it with the version required by the branch you pinned; do not run both Node.js selections in the same environment.
PDF generation
For ERPNext through version 16, install a compatible wkhtmltopdf package as part of the server preparation. Starting with version 17, Bench downloads Chromium for PDF generation, so wkhtmltopdf is not required. This is a release boundary: follow the PDF instructions for the branch you selected rather than copying a package command from an older guide.
Install Bench and initialize a bench
Bench is the command-line control plane for Frappe deployments. It creates the framework environment, manages sites and apps, builds assets and drives production configuration.
Install the current Bench package with uv:
uv tool install frappe-bench
bench --versionIf the shell cannot find bench after installation, add uv’s tool bin directory to the user’s PATH and start a new shell. Confirm the command runs as the non-root administrative user who will own the deployment.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Create a working directory and initialize the bench. Pin the Frappe branch when the selected release requires it:
mkdir -p ~/frappe
cd ~/frappe
bench init --frappe-branch version-15 my-bench
cd ~/frappe/my-bench
bench --versionThe branch name in this example is illustrative for a v15 deployment. Use the exact branch documented for your chosen ERPNext release. If you initialize without a branch, Bench may select a default that is incompatible with the ERPNext app you intend to install.
Initialization creates the Python environment, downloads Frappe and prepares the bench configuration. It does not create a site, install ERPNext, configure a public web server or make the system production-ready.
Create a site and install ERPNext
Create the site database and configuration
From the bench directory, run:
cd ~/frappe/my-bench
bench new-site example.comBench asks for the MariaDB root credentials and a password for the ERPNext site administrator. Use a strong, unique administrator password and store it in an approved password manager. The site name can be your real DNS name; using the final hostname avoids changing host mappings later.
Fetch the matching ERPNext branch
bench get-app --branch version-15 erpnextUse the branch matching the Frappe branch initialized earlier. Some release instructions use the shorter form bench get-app erpnext; the important part is that the fetched ERPNext branch and the framework branch are compatible.
Install ERPNext on the site
bench --site example.com install-app erpnextAt this point ERPNext is installed on that site, but production services may not yet be supervising workers or serving requests through Nginx. If the selected release requires migrations after an app or framework change, run them through the documented Bench workflow before opening the site to users.
Test in development mode
bench startUse the development server only for a short validation. Confirm that the login page loads, the administrator password works, static assets build correctly and a basic document can be created. Stop it with Ctrl+C; do not expose bench start as a permanent Internet-facing service.
Configure Supervisor and Nginx for production
Frappe describes Supervisor as the component that keeps Frappe processes running and restarts them after crashes. Nginx serves static files and proxies the remaining requests to Frappe. Both are required for a durable host-based deployment.
Generate Supervisor configuration
cd ~/frappe/my-bench
bench setup supervisor
sudo ln -s "$PWD/config/supervisor.conf" /etc/supervisor/conf.d/frappe.confIf a configuration file with the same name already exists, inspect it before creating another link. Reload Supervisor and verify its process groups:
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl statusGenerate Nginx configuration
cd ~/frappe/my-bench
bench setup nginx
sudo ln -s "$PWD/config/nginx.conf" /etc/nginx/conf.d/frappe.conf
sudo nginx -t
sudo systemctl reload nginxThe nginx -t check must pass before reloading. A syntax error, duplicate server block or stale symlink will prevent Nginx from reloading and can take the site offline.
Use the automated production command only when you understand its scope
Frappe also documents an easier path using:
sudo bench setup productionThis command changes system-level service configuration on the host. Review the generated files, confirm the bench path and user, and ensure you have a rollback plan before running it on a server with existing Nginx or Supervisor configurations. The same documentation warns against bare-metal installation and recommends Docker images for production, so treat the automated command as a convenience for a deliberate host-based deployment, not as a substitute for architecture and backup planning.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Verify the deployment before handing it over
Check every process group
sudo supervisorctl statusConfirm that the web process, Socket.IO process, queue workers, scheduler and Redis-related processes are running. A single running web process is not enough: without workers, background jobs and scheduled tasks will remain pending.
Test DNS and HTTP
Point the domain’s DNS record to the VPS address, wait for the record to resolve, and open the site over HTTP. The production guide states that once the domain maps to the server IP, the site should be live on that domain. Test from outside the VPS network so you detect firewall and DNS mistakes rather than only local routing success.
Apply basic host hardening
- Allow SSH only as needed and disable password authentication after key-based access is confirmed.
- Permit HTTP and HTTPS through the firewall; keep MariaDB and Redis off the public interface.
- Keep Ubuntu security updates current and schedule reboots when the kernel requires one.
- Record the bench path, site name, service files and recovery credentials in your operations documentation.
Enable HTTPS after HTTP works
Obtain a certificate for the final domain, configure Nginx for TLS, redirect HTTP to HTTPS and verify renewal before announcing the site. Certificate renewal is an operational task, not part of bench init; monitor expiry and test renewal in advance.
Maintain ERPNext after installation
Update with Bench
The documented update workflow is:
cd ~/frappe/my-bench
bench updatebench update pulls app changes, runs patches, builds assets and restarts Supervisor. Read the release and migration notes first, schedule a maintenance window for schema changes and watch the logs while the command runs.
Back up before upgrades
Take a backup before every framework or ERPNext upgrade, copy it off the VPS and perform a restore test on a separate environment. A backup that has never been restored is only an assumption. Include both the MariaDB data and the site’s public and private files.
Monitor the services that users depend on
- Supervisor process state and repeated worker restarts.
- MariaDB disk usage, connection errors and slow queries.
- Redis or Valkey health and queue depth.
- Nginx error rates, response status codes and certificate expiry.
- Disk space consumed by file attachments, logs and backups.
- Scheduler and background-job latency.
Review firewall rules and logs regularly. Document who receives alerts and what constitutes a rollback decision.
Troubleshoot common installation failures
“Package has no installation candidate” or dependency conflicts
Check the Ubuntu release and compare every installed runtime with the matrix for your Frappe branch. Ubuntu versions older than 24.04 may lack packages expected by current guidance. Do not solve the problem by randomly upgrading one component; either use a supported operating system or select a release whose documented dependencies match the system.
Bench command is missing after installation
Verify that uv’s tool directory is on the PATH for the same user who installed Bench. Start a fresh login shell and run bench --version. Installing Bench as root while running the bench as another user commonly creates separate PATH and ownership problems.
MariaDB authentication fails during bench new-site
Run sudo mariadb-secure-installation, confirm the MariaDB service is active and use the local administrative credentials requested by Bench. Check that the database version satisfies the selected branch instead of disabling authentication safeguards.
Workers are stopped or jobs never finish
Run sudo supervisorctl status. If a group is stopped, inspect Supervisor’s logs, confirm the bench path and user in the generated configuration, then reload and update Supervisor. Also verify that Redis or Valkey is running and reachable locally.
Nginx returns 502 Bad Gateway
Check Supervisor first: a 502 usually means the upstream Frappe process is stopped or listening on a different socket. Run sudo nginx -t, inspect the Nginx error log and compare the generated configuration with the active bench path. Reload Nginx only after the syntax test passes.
PDFs fail after an upgrade
Confirm whether the release still uses wkhtmltopdf. Versions through 16 require it; version 17 and later use Chromium downloaded by Bench. Installing both engines indiscriminately can hide the actual branch mismatch, so follow the selected release’s PDF setup and rebuild assets if the upgrade requires it.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →The site works locally but not on the domain
Check DNS resolution from an external network, the VPS firewall, Nginx’s server name and whether the DNS record points to the correct IPv4 or IPv6 address. Test HTTP before adding TLS; otherwise certificate and proxy errors can obscure a basic DNS problem.
Quick Recap
A practical handoff checklist
- The Frappe and ERPNext branches are recorded and compatible.
- The VPS runs Ubuntu 24.04 or newer, or another explicitly supported operating system.
- MariaDB, Python, Node.js, Redis or Valkey, Yarn, pip and PDF tooling match the branch matrix.
- The site was created with
bench new-siteand ERPNext installed withbench --site ... install-app erpnext. - Supervisor reports web, Socket.IO, queue, scheduler and Redis-related processes as running.
- Nginx passes
sudo nginx -tand serves the domain. - HTTP works before HTTPS is enabled, and certificate renewal has been tested.
- An off-server backup exists and has been restored successfully in a test environment.
- Update, rollback, monitoring and incident contacts are documented.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
