Basic coding guide for Frappe - ERPNext: Part 1

Alain Berger
Nov 26, 2017 · 11 min read

This is part 1 of a 2 part guide. Keep in mind that I am a farmer, not a programmer, so there are probably some errors or omissions. My hope is that the document will improve with comments and time.

Part 1 contains:

  • Introduction to Frappe / ERPNext
  • Our implementation experience
  • Personalization
  • Just read the instructions!
  • From hardware to fields: the whole stack
  • Before coding: set up your development environment

Part 2 contains:

  • How to code from scratch in ERPNext and Frappé Framework: Scripting
  • Custom scripts
  • Creating an application
  • More to come ...


In 2014, I decided to start a business, and after 16 months of intense work to meet our goals as a startup, it was painfully evident that we needed at least a basic ERP (Enterprise Resource Planning) to help with all our administrative tasks. As customer orders increased, the lack of proper coordination broke that startup environment that is so crucial to success. We had all the tools at our disposal in this great age of Internet: broadband connection, mac mini desktops and laptop, virtual switchboard services with Android mobile devices, WhatsApp, Dropbox, Gmail and spreadsheet programs (both Excel and Google online sheets). So, what were we complaining about?

All those tools are great, but a well-managed company requires a specific workflow and corresponding tools. Therefore, we needed something that could help us manage customers, suppliers, accounting, etc. At this point, the picture became more complex again: Quickbooks for accounting, Salesforce for customers, and we're back to the beginning! Separate applications that try to solve a single problem.

After the Christmas holidays of 2015, I was clear that we needed to integrate all this. For 2016, I had proposed objectives to solve our problem of commercial coordination and all the problems generated by using separate applications, in addition to the new issuance of costs and administration of subscriptions: you must pay to use some of these services, and although the prices are appropriate, you still have to pay bills separately for everything: PayPal solves this. But still, it has line items for each service.

I looked for profitable solutions and opted for open source options. I saw things like Gnucash, OpenBravo, Odoo, etc. and I was not very convinced. The issue of integration was still an important issue for us. Yes, we could develop procedures for this, even so we would have to program connections between our solutions: use our spreadhseet files neatly with Dropbox, integrate our mobile devices with Salesforce or similar, and maybe even program some kind of framework to integrate everything together . But wait, now we have to schedule something and we need to host it somewhere. We need to hire a programmer or two and invest some money to create this framework.

Trying to combine everything, find solutions and find only more problems exhausted me and the team. The idea of ​​the frame was brilliant, but nobody had done it, right? Incorrect! Someone had already addressed this problem in particular, and had done so majestically.

The answer came in February with a dark post in the forum after a Google search. The name: ERPNext , based on Frappé framework, a web application developed in Python and JavaScript.


Fast forward to June 2017, and we had already implemented a self-hosted version of this wonderful Open Source software. We opted for our own accommodation because I knew that we would modify it to a large extent. Integrates everything else beautifully, but the basic elements do it by itself: accounting, CRM, sales workflow, purchase and suppliers, stock management, etc.

We love the fact that it not only solved our basic integration needs, but also gave us more functions than we thought we would need: management tools, allocation and attachment of Bill-of-Materials: I can assign invoices to specific users or attach scanned copies of printed articles to validate your electronic counterpart documents. The framework itself is designed to be simple, but allows complex process management.

An example

One problem I used to have in my previous job was to solve problems that arose when a remote location manager ordered the items to form a central shopping location, and the item took more than 200 days to finally arrive. Who was to blame? Did the farm not order the item on time, or specify exactly what and how much did it need? Or the central purchasing manager did not comply? We had innumerable arguments and occasionally ended up in an unfortunate attack of anger from the parties involved (including me, I have learned better since then). Now, an existing item in the stock module is requested by the person in charge at the remote location, and this alerts the purchasing manager. The clock is working since the article is requested. The purchasing manager receives a quote, or if it is a regularly ordered item, Issue the purchase order to the supplier. At the moment the purchase order is validated, the specific article request changes the status. It is no longer necessary to waste time advising the interested party that their article has been ordered, ERPNext does it automatically! Then, when the article is finally received, all the parties involved are informed. Then, the accounting can pick it up and complete the transaction, including payment. All this can be seen immediately in the accounting module and you can see the cash flow reflecting this automatically.

The software itself allows you to make customizations based on the user, with little programming knowledge. All software works in an open source stack as a web application, allowing you to make modifications if you wish. It also has a large community of users, implementers and developers.

I will not expand all the wonders of ERP. Follow this in this publication, because our purpose is to create a basic guide or a map to make modifications based on scripts to the software, one of its most powerful features.


Since I started implementing it for our business, I had one goal in mind: to learn how to perform and eventually master custom software adaptations. All this to enable ERPNextto cover things such as consolidated declarations or taxes per unit of measure of article, or specific fiscal peculiarities of the country. The software, out of the box, is the only software that is already well advanced in the solution of many common or even peculiar commercial problems. Even today I'm still discovering new things that he can do, thanks to his frequent updates. Contrary to other custom-made commercial software, those with a custom software system will have to get used to a new type of problem: the updates they receive from the central development team, and not the other way around. What a great problem to have! Before, we used to wait for the developer to create the necessary customizations. In my previous job, They even caught us in a legal license fight that left the only developer willing, restricted by the court to update the current ERP software. Imagine that: You can not update Excel or Word because Microsoft is in a legal battle with one of the main developers. There is an error and you have to wait 5 years until the case is resolved (if it does). Everything that has gone withFrappé and the license structure of ERPNext based on GPL V3.0 .

Now we are happily operating all our transactions in ERPNext, and given its high personalization, I have decided to dedicate the time to expand the framework to meet our needs and solve specific problems of the country and the company.

Just read the instructions

Before starting, I must admit that, despite the large amount of resources available, as an occasional programmer, it took me some time to find the way to solve this ecosystem. How to learn to ride a bicycle or drive a car takes time.

So, this is my best attempt to write some instructions that help clarify how the whole framework works . I hope that by reading this, you can discover how to modify it to adapt it to your needs.

From hardware to fields: the whole stack


Ideally, you want to run this on a server machine or in a cloud-based service. I suggest Amazon Web Services or Digital Ocean . If you want to test and develop (or even configure a live server or install it for use on a single computer), install a virtual machine such as Open Source VirtualBox from Oracle right now, within which you install the operating system.

TK Add information about networks with the box for a single machine


The whole stack runs on Linux , specifically on Ubuntu . I suggest 16.04 LTS, but you can try any other version from 14.04 onwards. You can configure it in a server version for the real action, or if you want to develop it, use a desktop version of Ubuntu.

Software base

  • Python : high level programming language for general purpose programming. Most server-side commands are executed in Python.
  • MariaDB : the most popular database server, created by the original MySQL team.
  • NodeJS : framework / platform based on JavaScript.
  • Redis : storage of data structure in memory, used as database, cache and message agent
  • Wkhtmltopdf : command line tool to process HTML in PDF

The frame

Frappé Bench : this is the web framework on which everything else works. The framework puts all the resources below (Hardware, Operating System and Base Software) to work together efficiently. Theoretically, you can run any application you want in the framework


ERPNext : all the commercial tools I mentioned above are executed directly in this specific application.


Each application has several modules that provide specific functionality. In the case of ERPNext, some examples of modules are Accounts, Purchase, Sale, Human Resources.


Within each module, there is a collection of document types ( DocTypes) . A DocType collects data fields that fit a specific purpose. A purchasing module could have requests for materials, purchase orders or types of purchase receipt documents .


Each type of document collects several fields to store data within it. A material request doctype will have fields for the item name or the request date, but only a purchase order will have information on the date an order is placed with the supplier. A third type of document, a purchase receipt may have the date on which the business receives the item. The three dates mentioned are different pieces of information. In this example, you can clearly see that by storing these different dates, you can determine the number of days between a material request, or the time it takes for the supplier to ship, or the complete delivery time from the request to the delivery.

Other tricks

The framework is well designed, allowing you to save time on certain tasks, such as duplicating previously existing unique document types, or adding custom fields, document types or scripts without modifying the source code. You can even use the framework itself to create new applications for the framework. The development occurs in unison between the web browser and a terminal connected to the server.

Before coding: set up your development environment

Before jumping to some coding, you need to configure your development environment on your favorite computer (s). Regardless of the configuration, I believe that having all these tools installed from the beginning makes the development environment excellent. Therefore, common to any configuration:

  • Text editor : Textmate or Visual Studio Code (VSC). Any text editor will work. If you are on Windows, use your favorite text editor and an SSH client such as PuTTY . In Linux, simply configure Gedit or your favorite shell text editor ( Vim , Nano , etc.)
  • A decent command line application : iTerm . In Windows: ConEMU is a good console emulator that works in conjunction with PuTTY . For Linux, I use the native console.
  • Git : version control system. You will need it to contribute to the repository of your application or the frappe/erpnextmain repository.
  • Homebrew: used to install Linux style packages on the mac. Simply paste this code in the terminal indicator and press enter.
/usr/bin/ruby -e "$(curl -fsSL"

I have two ways to configure a development environment: VirtualBox and Docker .

Development environment - VirtualBox

Assume that you are using Mac OS X. It is a graphical user interface that allows you to run a virtual computer inside your computer.

  • VirtualBox : there are versions for each operating system, and this executes the Linux virtual machine that will run ERPNext
  • Samba : helps to modify files inside the virtual machine, from the host computer (or from any computer on the network!). This runs on the Linux machine. I connect to the shared folders from the Linux virtual machine and edit the code using Textmate or VSC.

The steps to configure a VirtualBox ERPNext development environment are the following:

  1. Download and install VirtualBox
  2. Download a VM image from ERPNext . Start with the production image , then move to develop it when you feel comfortable.
  3. Import the device in VirtualBox
  4. Configure the network either as a bridged connection to your current wifi or internet connection, or if working away from wifi, you can setup a Host-only network. More details on how to do this here.
  5. Start the virtual machine and on the VirtualBox screen, log in with the user name frappe and password frappe
  6. Discover the IP assigned with the ifconfigcommand
  7. Open an ssh connection to the server through your favorite terminal
  8. Add a root user and change to it
  9. Configure Samba (install, configure and restart)
  10. On the host computer use the browser or browser to navigate to the shared folders. I suggest you start at/home/frappe/frappe-bench
  11. Direct the browser of your host machine to this IP
  12. Log in as administrator with the password admin
  13. Enjoy!

Development environment - Docker

Docker was launched in March 2013 and its goal is to reduce the overhead created by the previous method. A dockable container does not require or include a separate operating system, but uses resources from the local operating system.

The steps to configure an ERPNext development environment based on Docker are the following:

  1. Download and install Docker Community Edition for desktop computers
  2. Install Git for the command line on your Mac OS. Do not get the desktop version, unless you want to. If you have installed Homebrew , open your terminal and then run the installation command for gitbrew install git
  3. On your terminal, find or create an appropriate folder and use it cdto change it.
  4. Clone the frappe_docker image of Githubgit clone --depth 1 && cd frappe_docker
  5. Once inside the frappe_docker directory created by the previous command, you can build the container using the commanddocker-compose up -d
  6. Then execute this command, only once:./dbench init
  7. Now you can start the containers with docker-compose start
  8. Once started, execute this command: ./dbench -s
  9. Now you can enter your container with docker exec -it frappe bashthis you will start a bash session on your docked frappe server.
  10. Point your browser localhost:8000and log in with the administrator credentials and password admin.
  11. Enjoy!

This link provides updated instructions on configuring frappe_docker .

Installing ERPNext

In case you perform a installation from scratch, you should have the following:

  • Ubuntu 14.04 to 16.04, CentOS 7+, Debian 7 to 8 and MacOS X
  • Python 2.7 installed (check in terminal with python --version , should return something like Python 2.7.11). If it is not installed, install it with sudo apt-get install python-minimal build-essential python-setuptools . If it's in MAC, with Homebrew installed, runbrew install python, brew install git.
  1. Open a terminal session and change to the /homedirectory.
  2. Change the rootuser withsu root
  3. Download and run the installation script for Linux
For Linux:wget Mac:curl "" -o

Once downloaded, run the script with:

python --develop --user frappe

Once configured, you can start the bank from the /home/frappe/frappe-benchdirectory with the commandbench start

At this point, you need to set up a test site.

TK Setting up a test site

If you just want to try ERPNext, configure for production. All processes will be managed by nginxand supervisorautomatically.

sudo python --production

Enabling Developer Mode

Once the installation has completed, you have to setup a test site. If you have installed a production server, then the site is already set, and you must enable developer mode. You can either edit the file on the terminal using Nano or your favorite text editor using Samba or with Docker. The file you need to edit is located here:

cd /home/frappe/frappe-bench/sites/[site_name]/site_config.json

Within the file, find the first .json element { and inside there will be two items: "db_name": "name", and "db_password": "password", so right after the last one, add a new line with the same indentation level, and then type:

"developer_mode": 1,

Make sure that you leave one space after the coma, and then save the file. If using nano: CTRL + X , Y , ENTER .

Frappé Thoughts

On Open Source, Design, Development and Community. By the makers of ERPNext.

    Alain Berger

    Written by

    Behold! There is a lot of lettuce, basil, kale, arugula, etc. (and plenty of useful, valuable software code too!)

    Frappé Thoughts

    On Open Source, Design, Development and Community. By the makers of ERPNext.

    Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
    Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
    Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade