ERPNext - Virtual Machine released!

The core ERPNext team are moving to docker as their preferred deployment architecture and have removed the Virtual Machine (VM) download for people wanting an easy entry into frappe or ERPNext ownership. So we thought we would build a minimal VM to make your life a bit easier.

We have tested the VM for use with ERPNext versions 11 to 14, but it will be useful for versions even older than that.

Hardware requirements

The Virtual Machine is configured with 1 CPU core, 1.5GB RAM and 30GB disk space. Any computer since 2010 should be able to run it with at least 2GB RAM. The Virtual Machine OVA file download is 5GB but will extract larger than that when you import it and will use more disk space as you build and use.

Disclaimer

The security settings of the Virtual Machine are not suitable for a hostile environment like the internet. It comes with no warranty or support but let us know here if you have problems (or not!) and we'll see what we can do to help.

Pre-requisites

1. First you'll need to download and install some host software. We recommend VirtualBox.
2. Next you need to download our Virtual Machine.
3. Then import it into VirtualBox and start it up. NOTE: the VM is configured for a NAT network interface by default.
4. If you're on Windows, you may need to install putty to make an ssh connection.

Connect via ssh

Whilst you can use the console that pops up to run the commands later on, we recommend connecting via ssh. Ssh port 22 is already forwarded to host port 2222, so connect using these settings:

1. Port: 2222
2. Host: localhost or 127.0.0.1
3. User: frappe
4. Password: frappe (use this for sudo commands too)

Building a bench

First you need to pick a frappe version. At time of writing (November 2022) version 14 is the latest.

If you're trying to restore an existing backup, you should pick the major version that is the same as the database. You can find this out by going to Help -> About and looking at the Frappe Framework number.

In all of the below commands, if you just want to use frappe and not ERPNext, you can remove the --install-app erpnext parts.

Switch node/yarn versions:

For all frappe versions except 11 you can use node.js version 14

$ nvm list
$ nvm use 14

Version-14 bench:

$ bench init --python /usr/bin/python3.10 --version version-14 --install-app erpnext v14
$ cd v14
$ bench get https://github.com/frappe/payments.git

Version-13 bench:

$ bench init --python /usr/bin/python3.9 --version version-13 --install-app erpnext v13

Version-12 bench:

$ bench init --python /usr/bin/python3.9 --version version-12 --install-app erpnext v12

Version-11 bench:

$ nvm use 8
$ bench init --python /usr/bin/python3.7 --version version-11 --install-app erpnext v11

Warning: At time of writing this will fail to build. Simply answer N to the question Do you want to rollback these changes? to keep the bench. Now you must downgrade the python MarkupSafe package & rebuild like this:

$ cd v11
$ ./env/bin/python -m pip install -U "MarkupSafe<2.1.0"
$ bench build

Creating a fresh site

You can create a fresh site with the commands below.

Name your site whatever you want, but if you plan to change the configuration to use DNS based routing (rather than the default port-based routing) you should pick your planned domain name. Like erp.domain.com. The bench directory will be one of v11, v12, v13 or v14.

$ cd <bench directory>
$ bench new-site --install-app erpnext <site name>

The MySQL root password is frappe

You will need to set up port number 80 for your site. The Virtual Machine is already set to redirect port 8080 on your host machine to port 80.

$ bench set-nginx-port <site name> 80
$ sudo bench setup production frappe
$ sudo supervisorctl reread
$ sudo supervisorctl reload
$ sudo bench setup sudoers frappe
$ bench restart

Restoring a backup

$ bench --site <site name> restore <path/to/database.sql.gz> --with-private-files <path/to/private-files.tar.gz> --with-public-files <path/to/files.tar.gz>

Depending on the size of the database and file archives this could take a while.

You will also need to copy your encryption key from your site config text file backup into the site_config.json file. It should look like this:

...
 "db_type": "mariadb",
 "encryption_key": "LoNgStRiNgHeRe",
 "pause_scheduler": 0,
...

Nano is a simple to use command-line text editor. Copy and paste the text to where the cursor is. Create a new line or replace the existing encryption key if there is one. Be careful with the commas at the end of the lines.

$ nano ./sites/<site name>/site_config.json

Use your arrow keys to scroll around and edit the file. CTRL+o to save and CTRL+x to exit.

Starting the scheduler

By default the scheduler will not run so things like backups and sending emails will not happen, but frappe and ERPNext will otherwise run fine. If you want to start it run this:

$ bench --site <site name> enable-scheduler

Congratulations!

You can now connect to your new virtual machine here: http://localhost:8080

Welcome to the future of web app and ERP software!