Read it carefully before begin installing anything
- Check for which user(ubuntu user account) you are installing a package
- Double Check and understand which package should be installed locally(for a specific user) and** which packages should be installed globally** (root/ administrator) user
- 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
- 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.
- At one point we had to configure mysql configuration, do not **duplicate **any **entry **there, you’ll thank me later 🙂
- Learn how to identify and kill a port as we are trying to work with WSL.
- 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
- 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
Package | Details |
---|---|
Python 3.11+ | |
Node.js 18+ | |
Redis 5 | Caching and Real-time updates |
MariaDB 10.3.x / Postgres 9.5.x | to run database-driven apps |
yarn 1.12+ | js dependency manager |
pip 20+ | py dependency manager |
wkhtmltopdf 0.12.5+ | for pdf generation |
cron | bench's scheduled jobs: automated certificate renewal, scheduled backups |
NGINX | proxying multitenant sites in production |
Required packages and Installation code | SKIP THIS STEP IF YOU ARE NEW
Install Git
Package | Installation Code | Check Version |
---|---|---|
git | sudo apt-get install git | git --version |
Install python
Package | Installation Code | Check Version |
---|---|---|
Python 3.11+ | `` | python3.11 --version |
python3.11-venv | `` | dpkg -l python3.11-venv |
python3.11-dev | `` | dpkg -l python3.11-dev |
python3-pip | `` | dpkg -l python3-pip |
python3-setuptools | `` | pip show setuptools |
pip 20+ | `` | pip --version |
Install NVM, Node, NPM, Yarn
Package | Installation Code | Check Version |
---|---|---|
nvm | `` | nvm --version |
Node.js 18+ | nvm install 18 | node -v |
npm | `` | npm -v |
yarn 1.12+ | `` | yarn --version |
Redis, mySQL, mariadb
Package | Installation Code | Check Version |
---|---|---|
Redis 5 | `` | redis-server --version |
MariaDB 10.3.x / Postgres 9.5.x | `` | mysql --version |
mariadb-server | `` | dpkg -l | grep mariadb-server |
mariadb-client | `` | dpkg -l | grep mariadb-client |
mysql | `` | `` |
redis-server | sudo apt-get install redis-server | redis-server --version dpkg -l | grep redis-server |
Some common packages
Package | Installation Code | Check Version |
---|---|---|
xvfb | sudo apt-get install xvfb | xvfb -version |
libfontconfig | sudo apt-get install libfontconfig | dpkg -l | grep libfontconfig |
wkhtmltopdf | sudo apt-get install wkhtmltopdf | wkhtmltopdf --version |
curl | sudo apt install curl | curl --version It comes with Ubuntu by default |
cron | `` | dpkg -l | grep cron It comes with Ubuntu by default |
NGINX | sudo apt install -y nginx | nginx -v |
Check all the packages version numbers, it’s a must, especially the node and yarn version
Install Frappe Bench, activate env
Package | Installation Code | Check Version |
---|---|---|
Install Frappe Bench | sudo pip3 install [projName] bench init frappe-bench --python python3.11 --frappe-branch version-15 | bench --version |
Activate virtual env | Inside the project folder, run source env/bin/activate | `` |
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 installUbuntu 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 runsudo -i
orsu
to switch to theroot
user, this will ask for the current user password
Once you switched the user tosab@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.
root
, you can runpasswd
and set thepassword
for theroot
This is a highly recommended step
Alternatively, if you want to change theroot@DESKTOP-KA3O8IP:~# passwd New password: Retype new password: passwd: password updated successfully
root
password directly without switching to theroot
user, you can use:
This will prompt you to enter and confirm the new password for the root user.sudo passwd root
- Now to switch the superuser to another user run
su sab
sab
is theusername
ofanother user account
in Ubuntu, that we created earlier - Give the newly created user sudo privileges:
If there is no return, it usually means, successful or truesab@DESKTOP-KA3O8IP:/root$ sudo usermod -aG sudo sab [sudo] password for sab: sab@DESKTOP-KA3O8IP:/root$
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:
- 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
- Install
Python 3.11
Now, installPython 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.
- Verify the Installation
Verify that
Python 3.11
is installed and set up correctly.
You should see the output.python3.11 --version
- Install
pip
forPython 3.11
Finally, install pip for Python 3.11
After completing these steps, you should havecurl -sS https://bootstrap.pypa.io/get-pip.py | python3.11
Python 3.11
installed on yourWSL
Ubuntu 22.04 LTS
, and you can proceed with theERPNext 15
installation.
Install Required Dependencies
- Update and Upgrade System
Ensure that your system is updated and upgraded.
sudo apt update sudo apt upgrade -y
- Install the necessary packages for ERPNext.
Now update sourcesudo apt install -y python3.11 python3.11-venv python3.11-dev libffi-dev mariadb-server libmariadb-dev libssl-dev wkhtmltopdf redis-server nginx
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)
Options | Select |
---|---|
Switch to unix_socket authentication [Y/n]: | Y |
Change the root password? [Y/n]: | Y |
It will ask you to set a new MySQL root password at this step. This can be different from the SSH root user password: | 123456 |
Remove anonymous users? [Y/n]: | Y |
Disallow root login remotely? [Y/n]: | Y |
Remove the test database and access it. [Y/n]: | Y |
Reload privilege tables now? [Y/n]: | Y |
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
, PDF
s, 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]