Install ERPNext using VirtualBox on FreeBSD 11.2

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 dalescott.net.

I found the simplest “install” for ERPNext on FreeBSD is to use the ERPNext Virtual Image with VirtualBox. VirtualBox is well-supported on FreeBSD, and phpVirtualBox provides a web-based GUI for headless servers. I’d like to thank Ian More and the phpVirtualBox community for phpVirtualBox, and also thank decke@FreeBSD.org for updating the FreeBSD phpvirtualbox port and package.

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 erpnext.org. 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).

The host server is a re-purposed media PC with Intel E6600 Core 2 CPU and 6 GB RAM (DDR2 PC2-5300) running 64-bit FreeBSD 11.2.  ERPNext performance has been completely satisfactory in a demo situation with several users. 

Install VirtualBox

I started by installing the virtualbox-ose-nox11 port, it has minimal dependencies and works nicely for someone who just wants to run headless virtual machines. 

First I first installed FreeBSD source.

% fetch ftp://ftp.freebsd.org/pub/FreeBSD/releases/amd64/11.2-RELEASE/src.txz % tar -C / -xzvf src.txz
Next I installed the ports collection (not previously required as I had previously been installing binaries using pkg). The FreeBSD sources are required to compile the virtualbox kernel module.
# portsnap fetch
# portsnap extract

I then installed virtualbox-ose-nox11 using pkg, which also installs the virtualbox kernel module (virtualbox-ose-kmod), 

% sudo pkg install virtualbox-ose-nox11

Unfortunately, currently on FreeBSD 11.2 the virtualbox kernel module must be compiled from source or the system will crash during boot (if the kernel module is loaded at boot). 

Compiling the virtualbox-ose-kmod is straightforward, but the build tools may need to be compiled first (or you could install them using pkg to save some time).  Make will refuse at first to install the kernel module because the one installed by pkg with virtualbox-ose-nox11 is still installed (by pkg). I followed the error messages and “make deinstalled” it, then “make reinstall”.

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

The post-install instructions then say to:

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

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

and then 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

You can then reboot the system to load the kernel module (or it can be loaded manually).

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

This does not start a virtual machine. I will use phpVirtualBox to manage virtual machines interactively. A vboxheadless rc.d script is provided if you wish to automate starting a vm at system 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 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>

“Install” ERPNext

Download an ERPNext Virtual Machine image (*.ova file) to /usr/home/dale/downloads (or some other suitably arbitrary location).

% 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). 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. 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, 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).

Cheers,
Dale

 

ERPNext vs Parts&Vendors Part 1

In the late 90’s, Parts&VendorsTM (PV) was the seminal multi-user application for embedded-electronics design teams to manage the parts and assemblies used in their various projects. It was a Windows desktop application and managed everything to do with an embedded-type product, including parts, vendors, manufacturers, purchasing, supporting documents, and even included rudimentary stock control to support small-volume manufacturing.

After almost 15 years on top, PV was discontinued January 2014. From the perspective of an outside observer, PV failed by not staying relevant and by creating an insurmountable technical debt. User teams were working more cooperatively with less authoritarian overhead, but the PV database did not suffer clients crashing or WAN latencies gracefully. Eventually best practices for Windows app development moved on and the effort to update PV became insurmountable.

Today, PV is still a standard that others can be compared to, especially ERPNext – a new web-based fully-featured open-source ERP system that is getting considerable well-deserved attention. However, before comparing PV to ERPNext, we need to first review some basic PV functionality.

Parts&Vendors UX / UI 

Item Master Tab

Parts are accessed through the Item Master tab.

Item Details

Selecting a part provides detailed information on sources (vendors) as well as other useful information.

Files and URLs

Documents and web sites can be associated with a part,

making it easy to access local documents or a web page for reference.

Unfortunately PV did not include a document control user interface to keep things in order, or utilities to verify document paths or list parts referencing a particular file. The shared directory approach worked well for a small conscientious team, or one with a dedicated “librarian”, but not with a more “entrepreneurial” team (if you know what I mean <wink>).

Assemblies

A part may be grouped with others in an Assembly. You can easily tell what assemblies include a particular part in PV from the part’s Used On tab. 

It’s also easy to navigate from a part to a containing assembly, and back. This is also called traversing a product tree containing child parts and parent parts.

An assembly has a Parts List (aka Bill-of-Materials or BOM) that lists its child parts.

Purchasing

Parts can be easily ordered,

An order can accumulate parts until it is placed with a vendor, eventually resulting in a purchase Purchase Order (PO).

In a smaller organization, the engineering team often does the ordering themselves. In a larger organization, a “real” purchase order may need to be created in a separate parallel system (e.g. QuickBooks). The exact process will depend on an organization’s size, structure, and history.

Receiving

When the ordered parts arrive, the PO is retrieved and the order item marked received, 

which updates the stock on hand.

The assembly Parts List is one way to see when the parts necessary to build an assembly are in stock.

Manufacturing

Once all the child parts for an assembly are in stock, a “Kit List” is generated from the “Build” tab for manufacturing. Stock on hand can be reduced for the kitted items, and later increased for the finished assembly when completed. 

Customers

PV can also manage clients and client orders, although the functionality is not integrated with stock control and closing an order does not reduce quantity on hand of the ordered items. The functionality is understandable though given it was never a goal of PV to be a POS (Point Of Sale) or CRM (Customer Relationship Management) system. 

 

This completes a quick refresher of Parts&Vendors. In the next post I will compare ERPNext to Parts&Vendors.

Product Lifecycle Management (PLM) using ERPNexth

This post is the second in a series on Using ERPNextSearch for “ERPNext” to find other posts in the series and please visit the demo on dalescott.net.

Product Lifecycle Management (PLM) is a body of knowledge concerned with managing everything about a product from cradle to grave. PLM encompasses product management, engineering design, product-specific business and manufacturing processes, new product introduction (NPI), and product data management. A PLM system integrates people, parts, processes and issues, and provides a trustable and transparent infrastructure backbone for the business.

Enterprise Resource Management (ERP) is a superset of PLM. ERP was born from a manufacturing need, but a modern ERP today includes accounting and financials, sales, customer relationship management, human resource management, and other core business systems – including PLM. However, modern ERP systems have also become complicated and expensive, and a successful implementation often requires that the business more conform to the ERP than vice versa. A new type of ERP is emerging, called Postmodern ERP. Postmodern ERPs are designed from the ground up to be simple and flexible, more capable of modelling a business than imposing conformity, and available to organizations of even modest requirements or means.

ERPNext is a postmodern ERP system, and includes basic PLM functionality. Although not as feature-rich as a dedicated PLM might be, ERPNext is capable for many situations, it is also less complicated, already integrated, and a capable starting point to build on. Features of ERPNext related to PLM include:

  • Integrated data. Items (parts), purchase specifications, engineering design documents, revisions, projects, issues, etc. All informtion is conveniently managed in one consistent system.
  • Visible, trusted, change management with social notification.
  • Scaled according to number of users, number of items and complexity of product trees, supply chain complexity, etc.

I will be following the Swift Construction Company’s development of the Aircraft Wireless in this tutorial, documented in the Maestro Project.

Goals

The goals of this tutorial are to:

  • Create child and parent items to model an assembly.
  • Identify item supplier information for purchasing, including purchase and OEM specifications.
  • Demonstrate a suitable change management process.

Future revisions of this post will expand on topics such as including anticipated purchase, process and labour costs for preliminary cosgt analysis, and defining appropriate work centers in the manufacturing process.

Definitions

Here are some terms defined in the context here.

  • CSV (Command Separated Value). CSV is a common text data interchange format, with data values separated by commas. E.g. ’12,”this is text, not a number”, 15.0′ might be one line from a CSV file (notice the text is quoted because of a contained comma). Although the acronym specifies the data element separator is a comma, other separator characters such as a tab or semi-colon are also often used.
  • ECO (Engineering Change Order). The name of a change management process often found in an engineering or manufacturing environment, which defines the process for making a change to an item, and thereby changing its revision level. Sometimes the ECO process is preceded by an Engineering Change Request (ECR) process in a two-phase ECR/ECO process.
  • OEM (Original Equipment Manufacturer). Items may be purchased from distributors, and there may be more than one distributor selling a particular OEM item. In this case, often it is the OEM item that is critical, not who it is purchased from.
  • Release. A release is a milestone in the development life-cycle of a top-level or child item, and is associated with a specific revision-level. A release provides a convenient point for synchronizing various project activities, including product features and capability, purchasing and manufacturing activities, press releases, pre-production and trade show demos, etc.
  • Revision Level. An item carries has a revision level, that can be used to reference the item, and its supporting documentation, as it existed at a particular point in time. An item, and its revision level, can be updated following a well-defined process.

Item Codes and Revision Levels

I will use an “8+2” format item code, with 8 digits to specify the unique item (aka part number), and 2 digits to specify the item’s revision level.

For example, see the following portion of the Aircraft Wireless product tree showing a custom inductor.

20000001-00,"IND,830UH,AIRCRAFT WIRELESS"
|-- 90000001-00,"WIRE,MAGNET,38AWG,POLY"
|-- 90000002-00,"MAG,FERRITE ROD,1/4IN X 4IN,MATL=61"
\-- 90000003-00,"TAPE,ELECTRICAL,3/4"",BLUE,VINYL"Create Items

I will need to create the parts required for the SCC Aircraft Wireless Release-1 prototype .  To create a new item, access the Item List in ERPNext and click New.

If necessary, a new unit of measure (UOM) can be created on the fly for the unit an item is managed in and consumed by.

The unit of measure for the wire in the custom inductor (PN 90000001-00) is centimetres (cm), meaning the wire will be inventoried in cm and consumed by the cm. However, it will be purchased in the vendor’s unit of measure, which is a Spool. Both cm and Spool will need to be created as they are not already defined in ERPNext’s UOM List.

Something to be aware of is that because centimeters are specified as the default UOM for the inductor wire, it means inventory will also be managed in centimeters. In an inventory audit, it will be necessary to convert from counted full spools to centimeters because the audit count will be in centimeters. Depending on the business, there are other out-of-box options which may work better in practise.

The purchase UOM for an item is specified in the Purchase Details section of the item master data.

When the purchase UOM for an item is different from the item’s default UOM, the relationship or conversation factor must be specified in the Units of Measure section of the Item master data. In the case of the inductor wire, the conversion factor from spool to cm is 588,264 (the datasheet for the wire indicates a spool contains 19,300 feet of wire, and 19300 ft x 30.48 cm/ft  gives 588,264 cm/Spool).

Supplier details are also entered in the Item master data, including specifying the OEM and OEM part number if relevant.

Attach Supporting Documentation

An image can be associated with an item in the item master data for the convenience of users in recognising or understanding the item. Files and other documents that specify or support the item can also be attached, such as the supplier catalogue page, a preliminary supplier quotation, or engineering design documents.

If a document already uploaded pertains to multiple items, the already-uploaded document can be attached instead of uploading a new document. It is also possible to enter item master data by importing CSV format data. This would likely be the preferred method when implementing ERPNext for an established organization.

Create Bills of Materials

Child items of a parent are specified using a Bill of Materials (BOM), including child item quantities. ERPNext revisions BOMs independently from Items, and creates BOM-20000001-00-001 as the initial BOM for Item 20000001-00.

Managing Change

Using the revisioning strategy outlined here, revising a child item in ERPNext can be done by simply duplicating it and increase the revision level in the Item Code. The revision level of the child’s parent item may or may be changed, depending on the policies of the organization. Generally a change in fit, form, or function mandates at least a revision level change, if not a completely new item with new root item code. The revision level of the parent may not be required to change if the fit, form or function of the parent has not changed as a result of the child’s revision.

If the revision level of the parent is not required to change, the parent’s BOM can simply be updated with the new child revision level. ERPNext will create a new BOM revision level, but the revision level of the parent item is not affected. If the revision level of the parent does change, a new BOM will need to be created for the new revision level of the parent (and listing the child at its new revision level).

Organizations typically have an approval process for revising a product, often called an Engineering Change Order (ECO) process. An approval signature document is commonly used to capture approval from stakeholders, including product management, engineering, sales, manufacturing, quality and finance. The signed approval document can be attached to the related item or BOM in ERPNext.

Summary

This has been a short overview of PLM using ERPNext. Although ERPNext is not a dedicated PLM system, its out-of-box capabilities are more than adequate to support basic PLM operations. Should additional capabilities be necessary, they can be developed on the ERPNext platform itself, or ERPNext’s advanced API can be used to integrate with a suitable dedicated PLM system.

Please leave a comment or use the contact form for more information.

ERPNext Tutorials

Enterprise Resource Management (ERP) was born from a manufacturing need, but a modern ERP today includes accounting and financials, sales, product lifecycle management (PLM), customer relationship management (CRM), human resource management (HRM), and other core business systems. However, modern ERP systems have also become complicated and expensive, and a successful implementation often requires the business more conform to the ERP than vice versa. A new type of ERP is emerging, called Postmodern ERP. Postmodern ERPs are designed from the ground up to be simple and flexible, more capable of modelling a business than imposing conformity, and available to organizations of even modest requirements or means.

ERPNext is a postmodern ERP. Rushad and his team created not only an incredible open-source software application, but also an entire eco-system, including a community of users and independent consultants, a supportive peer-to-peer help forum, and a recent addition, the ERPNext Foundation for project stewardship.

I will be taking a somewhat chronological journey through ERPNext, from an engineering perspective. Starting with the engineering team creating a prototype, then continuing through general customer release, the journey continues with changes to enhance quality, satisfy new customer needs, and reduce cost.

I will be following the Swift Construction Company’s development of the Aircraft Wireless in this tutorial, documented in the Maestro project. Also this list will be updated with links to the tutorials as they are published.

#1. Installing ERPNext

I started with the virtual machine image provided by ERPNext.org, hosting the vm using VirtualBox on FreeBSD.

#2. Product Lifecycle Management (PLM) using ERPNext

All the parts needed to build the initial Aircraft Wireless prototype will be created, including sub-assemblies with bills-of-materials (BOMs). Purchasing and supplier data will be entered for bought-in items, and appropriate documents will be submitted for custom or manufactured items. Revision levels will be used to assist in managing inevitable change.

#3. Purchasing using ERPNext (not yet published )

The parts needed to build a sub-assembly of the prototype (a custom inductor) will be purchased, received to stock, and paid for, with the development project bearing the costs. Initially, purchasing will be driven by the engineering project, then later by manufacturing scheduling after the Aircraft Wireless reaches production status.

#4. Manufacturing using ERPNext (not yet published )

Similar to the Purchasing tutorial, manufacturing will initially be driven by the engineering project, then later by manufacturing scheduling after the Aircraft Wireless reaches production status. Work orders will be created to manage work and collect cost.

#5. Managing projects using ERPNext (not yet published )

The concept of a project was first introduced in the Purchasing tutorial, when prototype costs were allocated to the Aircraft Wireless engineering project. Here project management will be explored further, including capturing time spent by engineering staff on the development project, and using Kanban project management (equivalent in many ways to the agile scrum process).

Other topics being considered include:

  • Purchasing from a BOM using ERPNext.
  • Managing Controlled Stock using ERPNext.
  • CRM using ERPNext.
  • Managing a Production ERPNext Site (keeping an ERPNext site up to date and QA considerations for business-critical software infrastructure systems).
  • Receiving  serialized stock items.
  • Serialize certain non-serialized stock when received (serialized with either vendor or local serial number).
  • Manufacture serialized stock in the form of sub-assemblies and final assemblies, using serialized and non-serialized stock.
  • “Un-manufacture” serialized product to sub-assemblies,  returning sub-assemblies to inventory following a QA re-verification process.
  • Reporting serialized sub-assemblies included in a serialized product (current and historical).

Please leave a comment if any of these topics are relevant to you, or to suggest other topics of particular interest.

Dale