Install ERPNext on FreeBSD 11.2 using VirtualBox

Search for other ERPNext-related posts. You may also visit the demo on dalescott.net.

The simplest way to “install” ERPNext on FreeBSD is to simply use the Virtual Image provided by the ERPNext project with VirtualBox.

The ERPNext project provides the Easy Install script for bare-metal installation but it has a number of Linux dependencies and will not work without changes on FreeBSD. Happily, the project also provides a fully configured virtual machine (based on Ubuntu Linux).

It may also be possible to use bhyve, the BSD hypervisor, with the virtual image, but the OVF file must first be converted to bhyve’s raw format.

Install VirtualBox

Install the virtualbox-ose-nox11 package for running headless virtual machines.

% sudo pkg install virtualbox-ose-nox11

The VirtualBox kernel module (virtualbox-ose-kmod) will also be installed, but it must be re-compiled from source and re-installed (at the very least, the system will crash when next re-booted once it has been configured to load the kernel module at boot). 

If not installed, install the ports collection for the kernel module source.

# portsnap fetch
# portsnap extract

If not installed, install FreeBSD sources required to compile the kernel module.

% fetch ftp://ftp.freebsd.org/pub/FreeBSD/releases/amd64/11.2-RELEASE/src.txz % tar -C / -xzvf src.txz

Compile and install the virtualbox-ose-kmod port. Make will first refuse to install the module because it is already installed (recall it was installed by being a dependency of virtualbox-ose-nox11). De-install the virtualbox-ose-kmod package, then re-install the newly compiled version.

% cd /usr/ports/emulators/virtualbox-ose-kmod
% sudo make install
% sudo make deinstall
% sudo make reinstall

Perform post-install configuration.

1) edit /boot/loader.conf to load the vboxdrv kernel module at boot,

# vi /boot/loader.conf
...
vboxdrv_load="YES"

2) increase AIO limits by editing /etc/sysctl.conf (my server is using AIO, for more information refer to the virtualbox-ose-nox11 pkg-message).

vfs.aio.max_buf_aio=8192
vfs.aio.max_aio_queue_per_proc=65536
vfs.aio.max_aio_per_proc=8192
vfs.aio.max_aio_queue=65536

Reboot the system to load the kernel module (or load it manually).

Make a mental note before doing an OS update to first edit /boot/loader.conf to not load the module. Otherwise the system will likely crash when next rebooted.

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

vboxwebsrv_enable="YES"
vboxwebsrv_user="dale"

and finally start the vboxwebsrv service.

% sudo service vboxwebsrv start
% sudo service vboxwebsrv status

The vboxmanage cli utility can be used to manage virtual machines but I will be using phpVirtualBox which provides a familiar GUI.

Install phpVirtualBox

phpVirtualBox can be installed from the FreeBSD ports collection but it currently has a dependency on PHP 7.1 while I have PHP 7.2. I installed phpVirtualBox manually to avoid pkg attempting to revert my PHP install to 7.1, and have not encountered any issues.

Download the latest release from the phpVirtualBox Github project . Follow the instructions in README.md file and on the wiki. Extract the project to /usr/local/www, and edit the configuration.

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

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

Configure the webserver to serve phpVirtualBox. I’m using the basic Apache 2.4 http server package. I added a virtual host definition to /usr/local/etc/apache24/extra/httpd-vhosts.conf to serve phpvirtualbox as a phpvirtualbox.dalescott.net.

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

Change the default phpVirtualBox login password to something secure after logging in for the first time.

“Install” ERPNext

Download the ERPNext Virtual Machine image (*.ova).

% cd ~/downloads
% wget http://build.erpnext.com/ERPNext-Production.ova

Using phpVirtualBox, create a new vm by importing the downloaded ERPNext-Production.ova Virtual Image file (File/Import). The OVF includes port forwarding rules to forward client port 80 to host port 8080 (for serving ERPNext) and a rule to forward ssh from client port 22 to host port 3022 (for system administration).

Start the vm and then login to ERPNext from a browser (e.g. www.dalescott.net:8080) 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, 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 system login (i.e. ssh) password for “frappe” user to something secure (or disable password authentication entirely in favor of key-based authentication).

Cheers,
Dale

 

Rotating Apache log files on FreeBSD

I needed to review an Apache httpd server error log file recently and even though the server had been rebooted only a month ago, I had to scroll through 95,000 lines before I got to the interesting part.

To make Apache’s log files more manageable, I configured them to roll every week using the FreeBSD standard newsyslog utility. newsyslog is run from cron, and in the default configuration runs every hour. This limits rolling logfiles to at most once an hour, but this is typically more than adequate for system log files.

I could have hacked newsyslog’s main config file /etc/newsyslog.conf, which would kept all configuration in one place for convenience. However this can lead to trouble when updating the system (because any new version would have to be manually merged with the edited old version), and keeping updating simple is generally a good idea. To deal with this, there are directives in the main config file to read additional optional configuration:

...
<include> /etc/newsyslog.conf.d/*
<include> /usr/local/etc/newsyslog.conf.d/*

Since the Apache server is third-party software, I created /usr/local/etc/newsyslog.conf.d/apache.conf containing the following:

# Apache
/var/log/httpd-access.log www:www 440 9 * $W1D4 J /var/run/httpd.pid 30
/var/log/httpd-error.log www:www 440 9 * $W1D4 J /var/run/httpd.pid 30

To understand what this means, the fields are: [logfile name] [owner-group] [mode] [count] [size] [when] [flags] [path to pid file] [signal]. Apache’s access and error log files will be rolled every Monday at 4am (system time), a total of 9 weekly archives will be kept (providing up to 10 weeks of logs counting the current log), and log file archives will be compressed using bzip2. Some other interesting points are:

  • For security, ownership of archived logs is set to www and the file mode is set to read-only for user and group, with no access by anyone else.
  • A SIGUSR1 signal (30) is sent to Apache to perform a graceful restart after rolling the log file.

For more information, see the System Logging section of the FreeBSD Manual as well as the man pages for newsyslog and newsyslog.conf.

To read a compressed log file, uncompress the file and pipe to less:

% sudo bzcat httpd-error.log.0.bz2 | less

Which is also equivalent to the simpler:

% sudo bzless httpd-error.log.0.bz2

Cheers!

FreeBSD on a BBG

Here’s the situation after installing FreeBSD on my BBG (BeagleBone Green), using an image published by the raspBSD project. No custom configuration or installing additional software has been done, although I have updated the package database. There’s more information on the install in a previous post.

For background, a BeagleBone Green (BBG) has a TI Sitara AM335x (1GHz ARM Cortex-A8) with 512MB DDR3 and 4GB eMMC (primary boot device), a micro SD socket (alternate boot device and additional storage), two USB connectors (one client and one host), ethernet, two Grove 4-pin connectors and two 46-pin 2×23 0.100″ pin headers with GPIO, SPI, I2C and other signals. 

Identification & Disk Use

Active Processes

I have two remote ssh sessions open.

Memory use

BeagleBone and FreeBSD

I recently purchased a BeagleBone Green (BBG) to experiment with FreeBSD on an embedded platform. The BBG has been available for a couple of years, and while I was tempted to get a BBG Wireless (BBGW), it would have meant ordering on-line and waiting for delivery. At least for initial development work I prefer a hard-wired connection, but also prefer to support local when possible.

BeagleBone Green

A BeagleBone Green (BBG) is a TI Sitara AM335x (1GHz ARM Cortex-A8 processor) with 512MB DDR3 and 4GB eMMC (which is the standard boot device), a micro SD socket (the alternate boot device and data storage memory), two USB connectors (one client and one host), ethernet, two Grove 4-pin connectors and two 46-pin 2×23 0.100″ pin headers. The original BeagleBoard emerged around 2010, and in 2013 was a winner in Embedded Computing Design’s “2013 Top Embedded Innovator award” in the Top Products Silicon category. The BeagleBone Black (BBB) was launched in 2013 as a lower-cost barebones BeagleBoard, and the BBG was launched in 2015 with two Grove connectors replacing the BBB’s HDMI connector.

Open-Source Hardware

A significant advantage of the BBG (and the other BeagleBoards and BeagleBones) for that the physical design (the schematics and pcb layout files) are provided under an open-source license. The BBG files are in a GitHub project using the MIT license. For someone designing a similar-but-different product, this can be a significant time saver.  The openness reportedly continues to other technical details of the design, such as the low-level details of power management.

FreeBSD

The RaspBSD project provides pre-built images for the BBG. The project originally provided FreeBSD images for the Raspberry Pi, but has expanded their scope to include the BBG (and BBGW). Once I sorted out how to select the alternate boot device (to boot from the micro SD card I had copied the RaspBSD image to) everything started falling into place.

The RaspBSD image is based on Head, which is new for me as I’m running 10.3-RELEASE on my web server. However, I’m looking forward to experiencing life on the edge.

I’m not sure if this is correct, but it seemed to work consistently. To boot from the micro SD card instead of eMMC, disconnect power then hold down the switch beside the micro SD slot, apply power and continue holding the switch for a count of three. After some testing (and being sure I could re-load the bundled Ubuntu-based system if I wanted), I used the script provided with RaspBSD to copy the FreeBSD image to the eMMC. This significantly improved boot time and also freed up the micro SD card for data storage.

Conclusion

For me, the BBG is the superior single-board unix computer for basing a new product design on. The openly provided design files and technical documentation, as well as easy access to GPIOs and other hardware resources on the two pin headers, provide a significant head start compared to having to start from scratch.