Skip to content

Instantly share code, notes, and snippets.

@amr3k

amr3k/ERPNext13-manual-installation-guide.md

Last active June 27, 2022 21:19
Show Gist options
  • Save amr3k/5412c731effddcc4ead61c6989ef9389 to your computer and use it in GitHub Desktop.
Save amr3k/5412c731effddcc4ead61c6989ef9389 to your computer and use it in GitHub Desktop.
Download ZIP
ERPNext manual installation guide (Debian 11 VPS)
Raw
ERPNext13-manual-installation-guide.md

Installation instructions

Feel free to Add/modify anything

Here we are using digitalocean Debian 11 droplet ($5/month)

Quick notes

We are going to use these emojis

  • 🖥️ refers to you server IP address

  • 👤 refers to your user name

  • 🧑🏽‍🤝‍🧑🏾 is the group name your user belongs to.

    It mostly is the same name as the 👤

  • 🔑 is the password you'll use with various settings.

    You can generate a strong password for this with the command openssl rand -hex 8

    Don't forget to save it somewhere safe

  • 🌍 is your website domain (Or subdomain)

Text editor

I personally prefer vim over nano but you can use whatever text editor you want.

So If you see (Edit some_file), You need to do vim some_file or nano some_file

System Update

  • Login as root to your server IP

    ssh root@🖥️

  • Add unstable repo to be able to install some dependencies we'll need later

    echo 'deb http://ftp.uk.debian.org/debian/ unstable non-free contrib main' >> /etc/apt/sources.list

  • Now update your system with

    apt update && apt upgrade -y

Adding a new user

  • First create a new user with a password (You can use the 🔑 you generated before)

    This command is interactive

adduser 👤
  • Add sudo privileges to the new user.
usermod -aG sudo 👤
  • Copy authorized keys to the new user home directory
cp -r /root/.ssh/ /home/👤/.ssh
  • Change ownership to the new user
chown -R 👤 /home/👤/.ssh
  • Logout then login again to the new user account: 
    ssh 👤@🖥️

Configuring SSH

  • Modify /etc/ssh/sshd_config: (Use nano or vim)

    Search these options and modify them

    • Use different port (Optional but recommended to reduce brute force attacks)

      Careful here: If you choose a different port other than the default 22, Remember to allow it in firewall settings in the next section, or else you won't be able to login with SSH

      • Port 1234 # Or any number 1-65535
    • Disallow root login (highly recommended)
      • PermitRootLogin no
    • Disable login with password (Optional but recommended to reduce brute force attacks)
      • PasswordAuthentication no
  • Finally, restart SSH server with
sudo systemctl restart ssh
  • Now logout then login again

    Note If you configured a new port, you'll use that port while connecting as follows:

    ssh -p PORT 👤NAME@🖥️
  • Add .local/bin/ to path: 
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
    • If you installed and using ZSH:
    echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.zshrc

Firewall configurations

  • Install with sudo apt install ufw.
  • Allow SSH, 80 and 443 ports using these commands: 
    sudo ufw allow ssh # Or the new port you chose above (e.g: sudo ufw allow 1234)
sudo ufw allow nginx
  • sudo ufw enable
  • Check if it's working with sudo ufw status

Setting up locale

echo "LC_ALL=en_US.UTF-8" >> /etc/environment
echo "en_US.UTF-8 UTF-8" >> /etc/locale.gen
echo "LANG=en_US.UTF-8" > /etc/locale.conf
sudo locale-gen en_US.UTF-8

Install basic required dependencies

sudo apt install git python3-dev python3-setuptools \
python3-pip virtualenv nginx wkhtmltopdf redis-server
  • Make sure python3 is the default by typing python --version.

    If it's not:

    • Delete the old one which is probably just a symbolic link to python2 in this case.
sudo rm /usr/bin/python
  • Create a new symlink
sudo ln -s /usr/bin/python3 /usr/bin/python

Installing Node.js via NVM

  • Use nvm following official guide

  • Install node.js

    Check the required node version for erpnext branch (In the time of writing this document, it is recommended to install version 14)

nvm install 14

Installing yarn

npm install -g yarn

Installing MySQL

sudo apt install mariadb-server libmysqlclient-dev
  • Setup mysql
sudo mysql_secure_installation

  • Edit /etc/mysql/my.cnf to add the following lines

    If these sections [mysqld] and mysql exist, Type below them respectively

    Note You may find those sections in other file in /etc/mysql/ so you'd better use something like grep to find them so you can add the code below.

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

[mysql]
default-character-set = utf8mb4
  • Add mysql user
mysql -u root -p
  • Type these commands
CREATE USER 👤@localhost IDENTIFIED BY '🔑';
CREATE DATABASE erpnext;
GRANT ALL ON erpnext.* TO '👤'@'localhost' with grant option;
FLUSH PRIVILEGES;
QUIT;
  • Restart mysql
sudo systemctl restart mariadb

Installing ERPnext

sudo mkdir /srv/www
sudo chown -R 👤:🧑🏽‍🤝‍🧑🏾 /srv/www/ # Remember UserName:GroupName
cd /srv/www/
pip3 install frappe-bench
# Check if bench installed by running `bench --version
bench init frappe-bench
cd frappe-bench
bench new-site 🌍 # Your website domain (Do you feel dizzy yet?)
bench get-app erpnext
bench --site 🌍 install-app erpnext
sudo apt -y install supervisor

Configuring ssl

Generating certificates manually

Browser will show it's not trusted site, so you'll need to use it behind cloudflare CDN

  • sudo mkdir -p /etc/letsencrypt/live/🌍/
  • # Replace "🏛️" with your company name (No whitespaces)
sudo openssl req -x509 -sha256 -nodes -newkey rsa:2048 -days 3650 \
-subj "/C=US/ST=Oregon/L=Portland/O=🏛️/OU=Org/CN=🌍" \
-out /etc/letsencrypt/live/🌍/fullchain.pem \
-keyout /etc/letsencrypt/live/🌍/privkey.pem

  • Edit sites/🌍/site_config.json.

  • Add those two lines.

    "ssl_certificate": "/etc/letsencrypt/live/🌍/fullchain.pem",
"ssl_certificate_key": "/etc/letsencrypt/live/🌍/privkey.pem",

Setup production

sudo $HOME/.local/bin/bench setup production 👤
sudo $HOME/.local/bin/bench setup lets-encrypt 🌍

Updating ERPnext

sudo $HOME/.local/bin/bench update --reset
sudo $HOME/.local/bin/bench migrate

Disable maintenance mode by editing sites/common_site_config.json and set maintenance_mode to 0

Common issues

Check if all services are running

sudo supervisorctl status

  • supervisor.service cannot restart

    You can always check system logs with sudo journalctl|grep supervisor

    In my case I found it missing section [supervisord] in ini!

    So the solution would be adding these sections in /srv/www/frappe-bench/config/supervisor.conf and restart the service

[supervisord]
nodaemon=true

[supervisorctl]

[inet_http_server]
port = 127.0.0.1:9001

[rpcinterface:supervisor]
supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface

Also Check /srv/www/frappe-bench/config/supervisor.conf for None values and replace it with the bench path command -v bench which most likely will be /home/👤/.local/bin/bench.

Don't forget to sudo systemctl restart supervisor.service.

  • If you encounter a problem with redis port

    Modify redis port in /etc/redis/redis.conf

  • Any time you see this message Your system is being updated. Please refresh again after a few moments in your website, it means the maintenance mode is active.

    To disable it you need to edit sites/common_site_config.json and set maintenance_mode to 0

  • Socketio error (connection refused)

    Check /socket.io in /srv/www/frappe-bench/config/nginx.conf .. Update proxy_pass to used http://localhost:9000 Update this section in /srv/www/frappe-bench/config/supervisor.conf

[program:frappe-bench-node-socketio]
; Check where your node is installed, in my case it is in (/home/👤/.nvm/versions/node/v14.18.1/bin/node) so I'm going to use it in the next line 👇🏼
command=/home/👤/.nvm/versions/node/v14.18.1/bin/node /var/www/frappe-bench/apps/frappe/socketio.js
priority=4
autostart=true
autorestart=true
stdout_logfile=/var/www/frappe-bench/logs/node-socketio.log
stderr_logfile=/var/www/frappe-bench/logs/node-socketio.error.log
user=👤
directory=/var/www/frappe-bench
@hhassey
Copy link

hhassey commented Apr 29, 2022

following this instrutions, on the step Install ERPNext

bench init frappe-bench

the system fails with:

FileNotFoundError: [Errno 2] No such file or directory: 'yarn'

ERROR: There was a problem while creating frappe-bench

Also the line right before that, has a typo says heck instead of check.

@amr3k
Copy link
Author

amr3k commented Apr 30, 2022

FileNotFoundError: [Errno 2] No such file or directory: 'yarn'

This is weird! Unfortunately I can't test it right now, could you tell me if the previous command went successful?

Also the line right before that, has a typo says heck instead of check.

Fixed, thank you.

@narduin
Copy link

narduin commented May 24, 2022

the system fails with:

FileNotFoundError: [Errno 2] No such file or directory: 'yarn'

ERROR: There was a problem while creating frappe-bench

I had the same error, resolved by installing yarn npm install --global yarn

@amr3k
Copy link
Author

amr3k commented May 24, 2022

the system fails with:
FileNotFoundError: [Errno 2] No such file or directory: 'yarn'
ERROR: There was a problem while creating frappe-bench

I had the same error, resolved by installing yarn npm install --global yarn

Thanks @narduin , I've just added this command after nvm section.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment