Installing Frappe ERPnext15 on WSL ubuntu 22.04 LTS

Read it carefully before begin installing anything

1. Check for which user(ubuntu user account) you are installing a package
2. Double Check and understand which package should be installed locally(for a specific user) and** which packages should be installed globally** (root/ administrator) user
3. Installing multiple versions of the same package is very common, but you must understand which version of the package is required and check if that package is what you are using, you can check that by running the version command
4. By default the root/ administrator user does not have any password, so set a password first, for the development it should be common among your fellow developers.
5. At one point we had to configure mysql configuration, do not **duplicate **any **entry **there, you’ll thank me later 🙂
6. Learn how to identify and kill a port as we are trying to work with WSL.
7. At one point we had to download the app from the frappe repository, the app is the same for everyone but the database is not, that database will make sure to reflect your app, not the codebase aka the app
8. You can download payments, erpnext, hrms, or any other app in any order, but when **installing the app, **you **must **follow the **chronology **provided at the end of this documentation

To all the folks coming from Node or PHP

Do not expect the same structure that you have seen in Node.js. Understanding Frappe’s structure will help you. Once you grasp it, the knowledge you gained from Node.js will start making sense again when you begin working on the front end in Frappe.

Pre-requisites

Required packages and Installation code | SKIP THIS STEP IF YOU ARE NEW

Install Git

Install python

Install NVM, Node, NPM, Yarn

Redis, mySQL, mariadb

Some common packages

Check all the packages version numbers, it’s a must, especially the node and yarn version

Install Frappe Bench, activate env

Check all the packages version numbers, it’s a must, especially the pip

Let's Start Installing Frappe ERPnex 15 on WSL Ubuntu 22.04 LTS

• Open windows Store and install Ubuntu 22.04Lts
• After opening the Ubuntu distro for the first time, it should install a couple of required packages and will ask for a username. This user account will be the default user account and the superuser (Administrator for Windows) for Ubuntu it is always root without any password
• I would strongly suggest you set the password as 123456 because this is easy to remember for development purposes
• The administrator or the superuser in Ubuntu is root and doesn’t contain any password too, you can run sudo -i or su to switch to the root user, this will ask for the current user password

    sab@DESKTOP-KA3O8IP:~$ sudo -i
    [sudo] password for sab:
    Welcome to Ubuntu 22.04.3 LTS (GNU/Linux 5.15.133.1-microsoft-standard-WSL2 x86_64)
  
    * Documentation:  https://help.ubuntu.com
    * Management:     https://landscape.canonical.com
    * Support:        https://ubuntu.com/advantage
  
  
    This message is shown once a day. To disable it please create the
    /root/.hushlogin file.

  Once you switched the user to root, you can run passwd and set the password for the root This is a highly recommended step

    root@DESKTOP-KA3O8IP:~# passwd
    New password:
    Retype new password:
    passwd: password updated successfully

  Alternatively, if you want to change the root password directly without switching to the root user, you can use:

    sudo passwd root

  This will prompt you to enter and confirm the new password for the root user.
• Now to switch the superuser to another user run

  su sab

  sab is the username of another user account in Ubuntu, that we created earlier
• Give the newly created user sudo privileges:

    sab@DESKTOP-KA3O8IP:/root$ sudo usermod -aG sudo sab
    [sudo] password for sab:
    sab@DESKTOP-KA3O8IP:/root$

  If there is no return, it usually means, successful or true

Configure the system locale to en_US.utf8

Open the file /etc/environment in a text editor and add the following lines at the end of the file:

sudo nano /etc/environment

Add these data to environment

LC_ALL=en_US.UTF-8
LC_CTYPE=en_US.UTF-8
LANG=en_US.UTF-8

Then run

sudo locale-gen en_US.utf8

sudo update-locale LANG=en_US.utf8

This is what it should look like

sab@DESKTOP-KA3O8IP:/home$ sudo nano /etc/environment
[sudo] password for sab:
sab@DESKTOP-KA3O8IP:/home$ sudo locale-gen en_US.utf8
/bin/bash: warning: setlocale: LC_ALL: cannot change locale (en_US.UTF-8)
Generating locales (this might take a while)...
  en_US.UTF-8... done
Generation complete.
sab@DESKTOP-KA3O8IP:/home$ sudo update-locale LANG=en_US.utf8

Install git

Let’s install git globally for the superuser

sudo apt-get install git

After installing git, you can simply run the git command to check if git is installed properly

Update/ Upgrade/ Install Python

Check the version of the python

sab@DESKTOP-KA3O8IP:/home$ python3 --version
Python 3.10.12
sab@DESKTOP-KA3O8IP:/home$

As you can notice the default version is 3.10 but the required version must be Python 3.11+

To install Python 3.11 on Ubuntu 22.04 LTS, follow these steps:

1. Add the Deadsnakes PPA (Personal Package Archive), a third-party repository maintained by community members to provide newer and older Python versions unavailable in the default Ubuntu repositories.First, you must add the Deadsnakes PPA, which contains newer Python versions.

   sudo apt update
   sudo apt install software-properties-common -y
   sudo add-apt-repository ppa:deadsnakes/ppa
   

2. Install Python 3.11 Now, install Python 3.11

   sudo apt update
   sudo apt install python3.11 python3.11-venv python3.11-dev -y

Now check all versions of python, python2 & python3

sab@DESKTOP-KA3O8IP:/home$ python3 --version
Python 3.10.12

sab@DESKTOP-KA3O8IP:/home$ which python3
/usr/bin/python3

sab@DESKTOP-KA3O8IP:/home$ which -a python
sab@DESKTOP-KA3O8IP:/home$ which -a python python2 python3
/usr/bin/python3
/bin/python3

sab@DESKTOP-KA3O8IP:/home$ whereis python3
python3: /usr/bin/python3 /usr/lib/python3 /etc/python3 /usr/share/python3 /usr/share/man/man1/python3.1.gz

Set Python 3.11 as Default (Optional)

If you want to set Python 3.11 as the default Python 3 version, you can update the update alternatives.

Add Python 3.11 to the alternatives:

sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1

Choose the default Python 3 version:

sudo update-alternatives --config python3

Select Python 3.11 from the list.

3. Verify the Installation Verify that Python 3.11 is installed and set up correctly.

   python3.11 --version

   You should see the output.
4. Install pip for Python 3.11Finally, install pip for Python 3.11

   curl -sS https://bootstrap.pypa.io/get-pip.py | python3.11

   After completing these steps, you should have Python 3.11 installed on your WSL Ubuntu 22.04 LTS, and you can proceed with the ERPNext 15 installation.

Install Required Dependencies

1. Update and Upgrade System Ensure that your system is updated and upgraded.

   sudo apt update
   sudo apt upgrade -y

2. Install the necessary packages for ERPNext.

   sudo apt install -y python3.11 python3.11-venv python3.11-dev libffi-dev mariadb-server libmariadb-dev libssl-dev wkhtmltopdf redis-server nginx

   Now update source

   source ~/.profile

   .profile is a shell script executed whenever you log into your shell.It typically contains environment variable definitions, PATH modifications, and other initialization commands.

   Purpose of source ~/.profile

   • Apply Changes: If you have made changes to your .profile file, running source ~/.profile applies those changes immediately to the current shell session. This is especially useful if you've added environment variables or modified your PATH.
   • Environment Setup: It sets up the environment variables and other settings defined in the .profile for the current session.
   • How It Works
     • source: This is a built-in shell command that reads and executes the content of a file in the current shell session.
     • ~/.profile: This is the path to the .profile file in the home directory.

Install node using NVM

nvm install 18

Or

nvm install node

To install the latest version of the node, use nvm (node version manager)

Install node using VOLTA

curl https://get.volta.sh | bash

Then

source ~/.profile

Finally,

volta --version

Install node using VOLTA

volta install node

Install yarn using VOLTA (Method - 1)

volta install yarn

or

Install Yarn (Method - 2)

This will not install the latest version of yarn

sudo apt-get install -y yarn

Use this method to install the latest version

Configure the Yarn repository:

First, you need to add the Yarn repository to your system's software sources:

curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -

echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list

Update your package list:

After adding the repository, update the package list:

sudo apt update

Install Yarn:

Now, you can install Yarn, ensuring you're getting the latest version from the newly added repository:

sudo apt-get install yarn

Check the Yarn version:

To verify the installation and check the version of Yarn installed, you can use:

yarn --version

Install Software Properties Common

Software Properties Common will help in repository management.

sudo apt-get install software-properties-common

Install MariaDB

sudo apt install mariadb-server mariadb-client

Install Redis Server

sudo apt-get install redis-server

Configure MYSQL Server

sudo mysql_secure_installation

When you run this command, the server will show the following prompts. Please follow the steps shown below to complete the setup correctly.

Enter current password for root: (Enter your SSH root user password)

Now we have EDIT MYSQL default config file

Before editing the default config file, check the mysql and mariadb version

Check mysql version

mysql --version

Check the mariadb version too

dpkg -l | grep mariadb-server
dpkg -l | grep mariadb-client

Edit MYSQL default config file

sudo nano /etc/mysql/my.cnf

Add the following block of code exactly as is:

[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

[mysql]
default-character-set = utf8mb4

DO NOT DUPLICATE ANY ENTRY, OTHERWISE YOU WILL FACE CONTINUOUS ERRORS

STOP HERE, AND CHECK IF ALL THE REQUIRED VERSIONS ARE PROPERLY INSTALLED AND YOU CAN ACCESS THOSE, OTHERWISE, YOU WILL FACE ERRORS CONTINUOUSLY

Edit the mariadb configuration ( Unicode character encoding)

sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf

Replace all content 50-server.cnf file with the following configuration

[server]
user = mysql
pid-file = /run/mysqld/mysqld.pid
socket = /run/mysqld/mysqld.sock
basedir = /usr
datadir = /var/lib/mysql
tmpdir = /tmp
lc-messages-dir = /usr/share/mysql
bind-address = 127.0.0.1
query_cache_size = 16M
log_error = /var/log/mysql/error.log

[mysqld]
innodb-file-format=barracuda
innodb-file-per-table=1
innodb-large-prefix=1
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

[mysql]
default-character-set = utf8mb4

Now press (Ctrl-X) to exit, then press y, followed by pressing the Enter key

Now check the mysql version

mysql --version

If everything goes well you can see the mysql version, otherwise, you may have this type of error

sabbir@DESKTOP-KANOFJB:~$ mysql --version
mysql: unknown variable 'pid-file=/run/mysqld/mysqld.pid'

Restart service

sudo service mysql restart

Install other packages

ERPNext functionality also relies on other packages we will install those in this step. These command will load fonts, PDFs, and other resources to our instance

sudo apt-get install xvfb libfontconfig wkhtmltopdf
sudo apt-get install libmysqlclient-dev

Navigate to the user folder using the cd command

home/[userName]

Install frappe-bench

sudo -H pip3 install frappe-bench

bench --version

If you face error like this
\ sudo: pip3: command not found

This means pip3 is installed locally for specific user

There are 2 solutions to this problem

Solution Temporary: The solution is to run the following command without sudo

pip3 install frappe-bench

bench --version

Long-Term Solution: Consider installing pip3 system-wide if you frequently need to use it with sudo

sudo apt update
sudo apt install python3-pip

Before going to next step check if the yarn version is correct

yarn --version

Initialise the frappe bench & install frappe latest version

bench init [projectName] --frappe-branch version-15 --python python3.11
ls

cd [projectName]/

bench start

Or, run the same command with the --verbose parameter to

bench init [projectName] --frappe-branch version-15 --python python3.11--verbose
ls

cd [projectName]/

bench start

At this point, if you visit the application with localhost, you can notice this

Activate the Python virtual environment

We can use the source command to activate the activate script located in the bin directory of our virtual environment.

source env/bin/activate

Create a site in the frappe bench

Create a site with the bench CLI

bench new-site [site-name]

bench use [site-name]

Now run the bench again

bench start

This time you can access frappe for the first time.

The default username is administrator

And the password is provided by you a while ago

Download frappe apps

These commands will only download the repo from the default frappe repository on GitHub

You don’t have to maintain any order at this step

bench get-app --branch version-15 erpnext
bench get-app payments
bench get-app hrms

Install all the apps on our site

Now let’s install all the apps that we downloaded earlier, keep in mind we have to install these apps chronologically

bench --site [site-name] install-app erpnext

If this command fails, you can notice that Frappe will ask you to run a command at the end of the error return, which is to reinstall the site, the following command will also remove any entry that you have inserted

bench --site [sitename] reinstall

Then, install the payments app

bench --site [site-name] install-app payments

Then, install the hrms

bench --site [site-name] install-app hrms

Chronology of installing apps

• Frappe (Global Repo)
• ERPnext (Global Repo)
• Payments (Global Repo)
• HRMs (Global Repo)
• Custom App (Extended)
• Bench start (Default frappe CLI)
• bench migrate (Default frappe CLI)

Get the app from a custom repo using Bench cli

Bench get app

bench get-app --branch version-15 [git https repo url]