Install ERPNext on FreeBSD

This post is the first in a series on Using ERPNext. Search for “ERPNext” to find other posts in the series and please visit the demo on

The absolute simplest way I have found to install ERPNext on FreeBSD (or any other OS) is to use the ERPNext Virtual Image with VirtualBox. VirtualBox is well-supported on FreeBSD, and phpVirtualBox is a great UI for headless servers. A big shout-out goes to Ian More for creating phpVirtualBox, and to the phpVirtualBox community, including who updated the FreeBSD phpvirtualbox port/package last.

Several years ago I attempted to install ERPNext on bare metal FreeBSD using the ERPNext Easy Install script, but found too many dependencies on Linux’isms and eventually switched the project server to CentOS. This time I used the virtual machine image provided by I first considered hosting the vm using bhyve, the BSD hypervisor, but bhyve does not directly support an OVF disk image and it became more convenient to use VirtualBox (reportedly it is possible to convert an OVF image to a raw image using qeum-image, which can then be used by bhyve).

I’m using a cast-off media PC for a server, with an Intel E6600 Core 2 CPU and 6 GB RAM (DDR2 PC2-5300). The OS is 64-bit FreeBSD 11.1.  ERPNext performance has been completely satisfactory, albeit under relatively light load so far. 

Install VirtualBox

# pkg install virtualbox-ose

The vboxdrv kernel module needs to be loaded at boot, done by editing /boot/loader.conf

# vi /boot/loader.conf

Reboot the system to have the kernel module loaded.

The user that VirtualBox runs as must be a member of the vboxusers group. For simplicity, I’ll run VirtualBox using my own username, although best practise would be to create a dedicated user.

# pw groupmod vboxusers -m dale

Edit /etc/rc.conf to run vboxwebsrv (the Virtual Box web interface daemon) using the provided startup script installed in /usr/local/etc/rc.d/

% sudo vi /etc/rc.conf


and finally start the vboxwebsrv service.

% sudo service vboxwebsrv start
% sudo service vboxwebsrv status

This however does not actually start a virtual machine. I will be using phpVirtualBox to manage virtual machines interactively. However, a vboxheadless rc.d script is also provided to start a virtual machine automatically during boot. 

Install phpVirtualBox

Install phpVirtualBox.

# pkg install phpvirtualbox

Edit the phpVirtualBox config.php file appropriately.

# vi /usr/local/www/phpvirtualbox/config.php

var $username = 'dale';
var $password = 'dale_login_password';

Finally configure the webserver to serve phpVirtualBox. I use Apache 2.4 and added a virtual host definition to /usr/local/etc/apache24/extra/httpd-vhosts.conf to serve phpvirtualbox as a

  DocumentRoot "/usr/local/www/phpvirtualbox"
  <Directory "/usr/local/www/phpvirtualbox">
    allow from all
    Options None
    Require all granted

“Install” ERPNext

Download an ERPNext Virtual Machine image (*.ova file) to /usr/local/etc/vbox (a suitably arbitrary location).

 % wget

Using phpVirtualBox, create a new vm by importing the downloaded ERPNext-Production.ova Virtual Image file (File/Import). It includes port forwarding rules to forward client port 80 (used by the vm to serve ERPNext) to host port 8080. There is also a rule to forward ssh from client port 22 to host port 3022.

Start the vm and then login to ERPNext from a browser (e.g. using the default credentials. The new site wizard will run and lead you through ERPNext configuration. Use a secure password when defining the initial (admin) user, and the wizard will delete the initial Administrator user (with default password) when complete. 

Once logged into ERPNext, you will likely want to setup email processing so that users will receive notifications outside of ERPNext. This will be valuable to understanding and appreciating ERPNext’s significant social aspect. You will also want to change the password for the configured system user to something secure (or even disable password authentication entirely in favour of key-based authentication).



4 Replies to “Install ERPNext on FreeBSD”

  1. Dear Dale
    I have successfully migrate from ERPNext 3 to 4.
    The error you posted is not relevant for python 2.7 and can be ignored but python needs to be recompiled on freebsd with the option SEM enabled. It is by default disabled. Following the migration guide after this works perfectly fine

    1. Thank you Samuel for your comment.

      For the benefit of others, Samuel’s comment relates to the first version of this post, which described an an unsuccessful attempt to install ERPNext directly on FreeBSD, following the Linux Easy Install script. Samuel reports re-compiling Python would have solved my roadblock.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.