This lesson is part of the complete Frappe Framework and ERPNext developer training series. In this one, we will explore how to create a custom app in Frappe Framework and install it on our running instance.
You will need to have SSL certificate installed on your instance to keep users of your system safe online. In Frappe Framework or ERPNext, this is a simple process.
Install snapd on your machine
sudo apt install snapd
Update snapd
sudo snap install core; sudo snap refresh core
Remove existing installations of certbot
sudo apt-get remove certbot
Install certbot
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
For one-step automatic ssl installation
sudo certbot --nginx
If you prefer manual installation,. do the following:
sudo certbot certonly --nginx
Certbot packages on your system come with a cron job or systemd timer that will renew your certificates automatically before they expire. So no further steps are required. If necessary, you can test automatic renewal for your certificates by running this command:
sudo certbot renew --dry-run
Wish you all the best.
ERPNext installation can be a pain in the neck, especially if you are getting started. In this article, I will take a step-by-step approach to configure our newly installed ubuntu 20.04 OS to set up an environment and install ERPNext. We will not leave any stone un-turned here. Let’s get to work!
In our first steps, we will make sure our system is up to date by running below commands:
$ sudo apt update
$ sudo apt -y upgrade
It is recommended to reboot your system whenever you do upgrade:
$ sudo reboot
$ sudo apt -y install vim libffi-dev python3-pip python3-dev python3-testresources libssl-dev wkhtmltopdf
$ sudo apt install curl
$ sudo curl --silent --location https://deb.nodesource.com/setup_14.x | sudo bash -
$ curl -sL https://dl.yarnpkg.com/debian/pubkey.gpg | gpg --dearmor | sudo tee /usr/share/keyrings/yarnkey.gpg >/dev/null
$ echo "deb [signed-by=/usr/share/keyrings/yarnkey.gpg] https://dl.yarnpkg.com/debian stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
$ sudo apt-get update && sudo apt-get install yarn
$ sudo apt -y install gcc g++ make nodejs redis-server
$ sudo apt -y install nginx
$ sudo apt install mariadb-server
Change authentication plugin.
$ sudo mysql -u root
USE mysql;
UPDATE user SET plugin='mysql_native_password' WHERE User='root';
UPDATE user SET authentication_string=password('your_password') WHERE user='root';
FLUSH PRIVILEGES;
EXIT;
Ensure you have the following settings for mysqld and mysql client as provided. I have put a file on a public github repo, so you can copy and replace the whole file.Â
$ sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf
$ sudo systemctl restart mariadb
A bench is a tool used to install and manage ERPNext on your Ubuntu system. We will create a user that will run the ERPNext system, then configure the system.
$ sudo useradd -m -s /bin/bash erpnext
$ sudo passwd erpnext
$ sudo usermod -aG sudo erpnext
Now it is time to update your PATH.
$ sudo su - erpnext
$ tee -a ~/.bashrc<<EOF
PATH=\$PATH:~/.local/bin/
EOF
$ source ~/.bashrc
Next, you need to create a directory for ERPNext setup and give erpnext
 user read and write permissions to the directory:
$ sudo mkdir /home/bench
$ sudo chown -R erpnext /home/bench
Next switch to erpnext user and install the application:
$ sudo su - erpnext
$ cd /home/bench
Install frappe bench and git
$ sudo apt install git
$ sudo pip3 install frappe-bench
The next step is to initialize the bench directory with frappe framework installed. Make sure you are still inside the /opt/bench directory:
$ bench init erpnext --frappe-branch version-13
Create a new Frappe site.
$ cd erpnext
$ bench new-site erp.codewithkarani.com
Download the ERPNext application from frappe Github repo. We will get version 13. You can get whichever version you like.
$ bench get-app branch version-13 erpnext https://github.com/frappe/erpnext
$ bench --site erp.codewithkarani.com install-app erpnext
$ bench start
Navigate to the IP address of your installation and the port number shown on the terminal after running. In the case of a local instance, use 127.0.0.1:8000
Ensuring your ERPNext system stays current is crucial for tapping into the latest features, improvements, and security enhancements. In this guide, we’ll steer you through the upgrade process from ERPNext version 14 to the more advanced version 15. The good news is that there’s no need to update your Ubuntu OS from version 22.04 to 23. However, it’s imperative to have Node.js version 18 or higher installed—a key step in this upgrade journey. Follow these straightforward instructions to maintain the agility and optimization of your ERP system, guaranteeing it operates at its peak efficiency.
cd /path/to/your/frappe-bench
This is very important. Ensure you have node 18 and later. In this guide, we will switch from node version 16 to version 18.
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
source ~/.bashrc
nvm install 18
nvm alias default 18
bench switch-to-branch version-15 frappe erpnext --upgrade
The bench migrate
command is crucial for managing database migrations in the frappe framework. Database migrations are changes to the structure of the database schema, and these changes may include creating new tables, modifying existing tables, or adding new fields to existing tables. The bench migrate
command facilitates the application of these changes to ensure that your database schema stays synchronized with the codebase.
bench --site [YOUR SITE] migrate
Supervisor is commonly used to manage the Gunicorn processes, which are responsible for serving the web application. When you make changes to your Frappe or ERPNext setup, such as updating the codebase or applying migrations, restarting the relevant processes is often necessary to apply these changes.
sudo supervisorctl restart all
bench version
This command should return version 15.X. Sometimes the update may be scheduled and therefore take a couple of minuted to complete. Ensure a seamless transition by checking your ERPNext site for proper functionality. Be vigilant for any errors during the upgrade process.
Sometimes you may get the below popup after the upgrade:
Failed to get method for command erpnext.e_commerce.doctype.e_commerce_settings.e_commerce_settings.is_cart_enabled with No module named ‘erpnext.e_commerce.doctype.e_commerce_settings.e_commerce_settings’
This can be resolved by running the below command:
bench retry-upgrade
It is quite frustrating to have your printouts looking all well only to get broken when you try to render them into a PDF that can be downloaded. If you have a similar case in your ERPNext or Frappe instance, where the letterhead doesn’t show on the PDF format, it is because your wkhtmltopdf package needs to be updated. In this article, I will summarize how you can quickly do this in different versions of Ubuntu.
After you have successfully completed the two stages, restart the supervisor if on production or restart your instance if in development to ensure changes take effect.
wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-2/wkhtmltox_0.12.6.1-2.jammy_amd64.deb
sudo apt install -f ./wkhtmltox_0.12.6.1-2.jammy_amd64.deb
wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-1/wkhtmltox_0.12.6-1.focal_amd64.deb
sudo apt install -f ./wkhtmltox_0.12.6-1.focal_amd64.deb
wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-1/wkhtmltox_0.12.6-1.bionic_amd64.deb
sudo apt install ./wkhtmltox_0.12.6-1.bionic_amd64.deb
wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-1/wkhtmltox_0.12.6-1.xenial_amd64.deb
sudo apt install ./wkhtmltox_0.12.6-1.xenial_amd64.deb
Good software design will emphasize the importance of separating the database from the software application. The server where the database is hosted needs an extra layer of protection as it contains all the data. This is sometimes known as remote database setup. This can also be achieved in ERPNext and the Frappe Framework.
In this article I will demonstrate to you how this can be achieved with simple steps.
After you have installed your database in the remote server (You may use the script provided on my GitHub repository), you will need to set it up to allow remote connections by doing the following:
Edit MariaDB configuration file to accept remote connections by changing its bind-address from 127.0.0.1 to 0.0.0.0
sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf
Login to your MySQL and create a database user that Frappe will use to authenticate.
CREATE USER 'root'@'[IP ADDRESS FOR ERPNext HOST]' IDENTIFIED BY '[YOUR PASSWORD OF CHOICE]';
Grant the created root user permissions to make changes to the created databases.
GRANT ALL PRIVILEGES ON *.* TO 'root'@'[IP ADDRESS FOR ERPNext HOST]' IDENTIFIED BY 'YOUR PASSWORD OF CHOICE' WITH GRANT OPTION;
Flush the privileges to effect changes to the database and log out from MySQL.
FLUSH PRIVILEGES;
EXIT;
Restart MySQL server to effect all the made changes.
sudo service mysql restart
Test the connection using the below command:
mysql -u root -h [IP ADDRESS FOR DATABASE HOST] -p
If the request doesn’t go through, you may need to ensure that there is no firewall that blocks connections to TCP port 3306 of the MySQL server. We use the below command to allow an IP address on Ubuntu servers:
ufw allow from [IP ADDRESS FOR ERPNext HOST] to any port 3306
bench set-mariadb-host [IP ADDRESS FOR DATABASE HOST]
Restart supervisor if your instance is in production mode
supervisorctl restart all
If your instance is in development mode, restart bench
bench restart
At this point you may decide to test the connection or dive in and create a new site. The database that Frappe will create will be in the server you just set up 🙂
bench new-site erp.upeosoft.com --mariadb-root-password [YOUR PASSWORD OF CHOICE]
When you are a software developer, GitHub is a handy tool when it comes to version control. GitHub also helps us to manage how code goes to the production server. When doing development with ERPNext and/or the Frappe Framework, we can also manage our code with GitHub.
All development and any customization needed is done on the local instance. Once a feature is working well locally, or maybe its a completed bug fix, we push the code to whatever GitHub branch that is managing the code. Our remote instance then pulls the code from GitHub.
There are two ways for getting the code to the live server from GitHub. You can either Pull the code manually or you Automate with GitHub actions. Either way, this is a very effective process that will ensure your custom app is safe and any customization you do is being launched smoothly.
This is all taken care of in this series.
When you install ERPNext for the first time, it sometimes gets frustrating when the fields are not properly arranged as you would expect. I will share some of the commands I have found useful in this article.
bench build – This command has more abilities if you supply additional options, but we just run it as this to build our app assets.
bench migrate – This command also has greater capabilities, but we are interested in only this basic one. It will run patches, sync schema and rebuild files/translations.
The bench migrate command may sometimes require you to supply the site name, especially when your instance is on production mode. In this case, just run:
bench –site [xyz] migrate
The last command I would like to share today, which clears your browser cache just in case you have cached content that may be causing this problem:
bench clear-website-cache
Here is a sample of the issue we are discussing here:
If you have other ways to solve this problem, please share in the comments section below.
When ERPNext is installed in development mode, you will have to restart the instance with the bench start command every time you want to access it. You can however start your instance when the server boots by setting up your instance for production.
In this article, I will show you a simple way to move your instance from development mode to production mode.
We will be using Supervisor to manage to manage the ERPNext process and Nginx as a reverse proxy to access the ERPNext process without using port 8000.
There are two ways this can be done. I will start with the simple and straightforward one.
Run the below commands from your bench directory:
sudo bench setup production [BENCH USER]
sudo supervisorctl restart all
If you are successful, your instance should be in production mode.
If this didn’t work for you, follow the following steps:
First, change the user to your bench user and install Supervisor and Nginx with the following command:
su - erpnext sudo apt-get -y install supervisor nginx
Next, install the frappe-bench add-on with the following command:
sudo pip3 install frappe-bench
Next, run the following command to configure ERPNext for a production environment:
sudo /home/erpnext/.local/bin/bench setup production erpnext
You should see the following output:
Site erpnext.example.com assigned port: 80 $ sudo /usr/bin/supervisorctl reread erpnext-redis: available erpnext-web: available erpnext-workers: available $ sudo /usr/bin/supervisorctl update erpnext-redis: added process group erpnext-web: added process group erpnext-workers: added process group nginx: the configuration file /etc/nginx/nginx.conf syntax is ok nginx: configuration file /etc/nginx/nginx.conf test is successful $ sudo systemctl reload nginx
At this point, ERPNext is installed and configured to run on port 80. Now, open your web browser and type in Your URL without the port.
When you install ERPNext for the first time, you may realize that you are running the developer version of both Frappe and ERPNext. You cannot proceed with the developer branch, as things keep changing, some of which may not be tested thoroughly.
In this video, you will learn how to switch from developer branch to the official release of both apps. I will also show you how to resolve all the issues that arise when you do the movement.
To switch from Developer to Official Branch, we run the command:
bench switch-to-branch version-13 frappe erpnext
After this has completed executing, the instance will prompt you to run the following command:
bench update –patch
When you run this command, most of the time you will get an error message that says:
No module names bleach_whitelist
When this happens, all you need to do is install this module in your environment. Note, I said environment. If you just run the command without specifying that you are installing it on the environment, it will not work. Frappe runs on an environment, and therefore all dependencies need to be installed on the environment.
Make sure that you are on the root directory of your instance, where you can see the env directory. Run the following command:
./env/bin/pip3 install bleach-whitelist
When this is successful, the command bench update –patch should succeed.
Next, run the below command to gather all requirements and set them onto your instance:
bench setup requirements
When this is successful, your instance should be accessible. You may however notice that the instance has not loaded assets. To load and compile assets to yout instance, run the following command:
bench build
After this is done successfully, your assets will be setup properly, and your instance will look fine. In some cases, you may get the message that your system is being updated. Please refresh again after a few moments. If you encounter such, its a configuration issue. Open sites/common_site_config.json file and locate maintenance_mode. You will find that its value is set to 1. Change the value to 0, so the value should look as shown below: