ERP Installation
ERP Install
Release notes
This manual is valid for the .NET 5 version of the ERP system.
If you updated the .NET version, you might be able to use newer OS versions.
The system was tested and works on Linux Ubuntu 20.04. It might work on other Linux OS versions or flavors but it has not been tested.
Depending on the system configuration, you might need to install a separate machine for the database. Follow the same instructions for the OS installation.
The user’s name used in this manual is pos and the password is 1qaz2wsx.
1 Installing on Oracle VM Box
If you want to run the ERP in an Oracle VM Box virtual machine you need to configure the following things.
Create a Linux type VM and use the settings in the image below.
Network mode (default is NAT) must be set to Bridged Adapter for it to work with a static IP. After the OS installation (see next chapters) set the static IP.
Check if you can see the machine by pinging-it:
> ping 192.168.1.10
1.1 Enable copy-paste between host and VM
1.1.1 Install Guest Additions
Guest Additions are required for features like shared clipboard, drag and drop, better video support, etc. Start your VM. From the VirtualBox top menu, go to:
Devices → Insert Guest Additions CD image…
A virtual CD will appear in the VM. If it doesn’t auto-run, open a terminal in the guest, mount and run the installer manually:
> sudo mkdir /mnt/cdrom
> sudo mount /dev/cdrom /mnt/cdrom
> sudo /mnt/cdrom/VBoxLinuxAdditions.run
Reboot the VM if installed successfully. To check if it’s installed, run:
> lsmod | grep vboxguest
You should get something like the next image:
1.1.2 Fixing dependencies
If you get this message when installing Guest Additions, you might need to install some other software dependencies before you can install Guest Additions.
> sudo apt update
> sudo apt upgrade
> sudo apt install make perl
You might need to install Aptitude to fix broken dependencies:
> sudo apt install aptitude
> sudo apt update
> sudo aptitude install build-essential dkms linux-headers-$(uname -r)
> reboot
1.1.3 Enable Clipboard Sharing in VM Settings
On the host machine (before starting the VM), Select your VM in the VirtualBox Manager.
Click Settings → General → Advanced, and set:
- Shared Clipboard: Bidirectional (or Host to Guest, depending on need)
- (optional) Drag and Drop: Bidirectional (if you want drag-and-drop files)
The drag & drop functionality might not work even after you configured all of this. If that’s the case either install a Remote Desktop application or create a shared folder (see below how).
1.2 Create a share folder if drag & drop doesn’t work
In the VirtualBox Manager, select your VM → Settings → Shared Folders, and click Add (+) then set:
- Folder Path: Choose a folder on the host.
- Folder Name: This is how it appears inside the VM.
- Check Auto-mount and optionally Make Permanent.
If the folder name is SharedFolder, it will be auto-mounted to /media/sf_SharedFolder.
Add Your User to the vboxsf Group. This gives your user access to the mounted folder:
> sudo usermod -aG vboxsf $USER
2 Installing the Linux OS for ERP and Database
2.1 Recommendations
Use the same User Name and passwords across the OS and database. This will make your life easier when setting up the connectivity. You can use different passwords and user names but you need to keep track of them between setups and environments. The default User Name is pos for the OS and database for standalone systems. The User Name is also used in the startup and installation *.bat and *.sh files.
2.2 Step 1: VM installation
This is an optional step but it is recommended. Install the OS on a VM for easier backup and cloning. Cloning might be used to create Staging or Test environments.
We used PROXMOX in our production systems, but any other VM software will do. Follow the instructions of the specific VM you are using and install the version of the OS needed.
2.3 Step 2: OS installation
Install the version of Linux OS mentioned at the beginning of this chapter. Other versions might work but you are going to have a tough time setting things up, since for example, .NET5 is missing from the latest Linux repository.
After installation run these commands to update the OS components:
> sudo apt-get update
> sudo apt-get upgrade
2.3.1 Update sudoers file
Some commands need to be run in a SUDO mode. Update the sudoers file so the User can run the commands in SUDO mode by default without a password being asked:
> sudo -i
~#> cp /etc/sudoers /root/sudoers.bak
~#> visudo
This will open the editor.
Append the following entries to run ALL commands without a password for a user in any %GROUP named pos (where ‘pos‘ is the user’s name and group’s name):
pos ALL=(ALL) NOPASSWD: ALL
%pos ALL=(ALL) NOPASSWD: ALL
#ASPDOTNET
Defaults env_keep += “ASPNETCORE_ENVIRONMENT”
Defaults env_keep += “DOTNET_ENVIRONMENT”
Reboot the system:
> reboot
2.3.2 Set the IP address
The machine that runs the ERP system needs a fixed IP address. This address will also be set in the appsettings.json files for the specific environment. Keep a pool of at least 2-3 reserved IP addresses for the other environments if needed.
The default IP address for a stand-alone system is 192.168.1.10. Use the OS UI to set this address.
Reboot the system:
> reboot
2.4 Install a Remote Desktop application (optional)
You need to be able to easily connect and update the ERP applications. For this it is recommended to install a Remote Desktop application such as Rust Desk, Any Desk, Team Viewer or other.
On most Linux distros you can either download the installation file from the application’s website or install directly from the integrated software delivery application.
Do not forget to set up unattended access and password.
2.4.1 Install a virtual monitor (warning)
This might break a VM’s video drivers and it won’t boot anymore. Create a backup before this step.
VMs usually implement a virtual monitor. If you install the OS on a barebone machine that might be missing the monitor, you need to install a virtual monitor application to allow the Remote Desktop application to run and render correctly.
For the Ubuntu 20.04 distro we can use the xserver virtual monitor. To install it run the following commands:
> sudo apt-get install xserver-xorg-video-dummy
> cd /usr/share/X11/xorg.conf.d
> sudo touch xorg.conf
> sudo nano xorg.conf
This will create and open the config file for the virtual monitor.
The contents of the file configure the behaviour of the dummy monitor. In our case it is a 1600×1200 pixels monitor.
Section “Device”
Identifier “Configured Video Device”
Driver “dummy”
EndSection
Section “Monitor”
Identifier “Configured Monitor”
HorizSync 31.5-48.5
VertRefresh 50-70
EndSection
Section “Screen”
Identifier “Default Screen”
Monitor “Configured Monitor”
Device “Configured Video Device”
DefaultDepth 24
SubSection “Display”
Depth 24
Modes “1600×1200”
EndSubSection
EndSection
3 Install .NET
The ERP system is built using .NET5 at the time of this document. This document will contain specific commands referring to the .NET5 framework and Ubuntu 20.04. Update the command s accordingly if you are using another OS than the one recommended or a newer framework version.
3.1 Update the package library
Update the packages by running:
> sudo wget https://packages.microsoft.com/config/ubuntu/20.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
> sudo dpkg -i packages-microsoft-prod.deb
> sudo apt update
3.1.1 Install https (optional)
If needed you can optionally install the https library:
> sudo apt install apt-transport-https
3.1.2 Install libssl (optional)
If you are going to serve https pages you will need to install libssl:
> sudo wget http://archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1-1ubuntu2.1\~18.04.20_amd64.deb
> sudo dpkg -i libssl1.1_1.1.1-1ubuntu2.1~18.04.20_amd64.deb
If you encounter problems when installing libssl, runs this:
> echo “deb http://security.ubuntu.com/ubuntu focal-security main” | sudo tee /etc/apt/sources.list.d/focal-security.list
> sudo apt-get update
> sudo apt-get install libssl1.1
3.2 Install .NET5
To install .NET5 run:
> sudo apt-get install -y dotnet-sdk-5.0
Check if the framework installed successfully:
> dotnet –list-sdks
This should return:
5.0.408 [/usr/share/dotnet/sdk]
Check the runtime:
> dotnet –list-runtimes
This should return:
Microsoft.AspNetCore.App 5.0.17 [/usr/share/dotnet/shared/Microsoft.AspNetCore.App]
Microsoft.NETCore.App 5.0.17 [/usr/share/dotnet/shared/Microsoft.NETCore.App]
4 Install NGINX
The UI is served by the NGINX server. Install it with the command:
> sudo apt install nginx
Reboot the system.
> reboot
5 POSTGRES Database installation
After installing a Linux distro and updating it, setting its IP address you can install the database. The database can be installed on the same machine with the ERP application or on a separate machine.
References:
https://www.cherryservers.com/blog/how-to-install-and-setup-postgresql-server-on-ubuntu-20-04
5.1 Install POSTGRES
To install POSTGRES run:
> sudo apt-get -y install postgresql
This will install the latest version of the POSTGRES database engine. If you have troubles with it (while you shouldn’t) you can try installing the version that is tested and works (version is 12.22).
To check what version of POSTGRES you have run:
> pg_config –version
This should return:
PostgreSQL 12.22 (Ubuntu 12.22-0ubuntu0.20.04.4)
5.2 Create a database user
Use the same name for the database as the one used for the user of the Linux installation. This is not mandatory but recommended. The database user’s name will have to reflect in the ERP database connections strings.
> sudo -u postgres createuser –interactive
This will open an interactive screen. The user’s role will be set to superuser.
5.3 Create a database for the ERP
To create a new database run:
> createdb erp
5.4 Log-in to the database
After creating a database user and a database connect to PSQL to test the connection. To open a connection the database, run:
> psql -d erp
Check the connection info by running:
# \conninfo
This should return:
You are connected to database “erp” as user “pos” via socket in “/var/run/postgresql” at port “5432”.
5.5 Set the user’s password
We need to set a password for out new user so we can connect from outside to the database. To set the password, after connecting to the DB engine, run the command:
> psql -d erp
# \password pos
This will prompt you to enter a password:
Enter a password
It is recommended to enter the same password used for the OS or a password from the appsettings.json file. The password needs to be entered also in the appsettings.json connection string.
Type exit to exit the database configuration screen.
5.6 Configure Database network access
By default, POSTGRES does not allow connections from outside the localhost. To allow access from the network you need to configure the pg_hba file.
> cd /etc/postgresql
> ls
This will list the folders containing the version(s) of the POSTGRES installation. Replace the <version> with your version.
> sudo nano <version>/main/pg_hba.conf
Append a new connection policy (a pattern stands for [CONNECTION_TYPE] [DATABASE] [USER] [ADDRESS] [METHOD]) in the bottom of the file.
host erp pos 0.0.0.0/0 md5
This allows all connections from any IP.
Replace 0.0.0.0/0 after testing only the ERP server address to avoid unauthorised access.
An example of a complete configuration is this:
#Internet access for ERP
host erp pos 86.122.0.0/16 md5 # this is a range for the ISP
host erp pos 192.168.1.10/32 md5 # this is the actual ERP server
host erp pos 192.168.0.0/16 md5 # this is a range for the local network
Save the changes and restart POSTGRES:
> sudo systemctl restart postgresql
5.6.1 Configure listen ports
In the same <version> folder you will also need to edit the postgresql.conf file:
> cd <version>/main
> sudo nano postgresql.conf
Go to the CONNECTIONS AND AUTHENTICATION section and edit the listen_addresses parameter:
#——————————————————————————
# CONNECTIONS AND AUTHENTICATION
#——————————————————————————
# – Connection Settings –
listen_addresses = ‘*’ # what IP address(es) to listen on;
# comma-separated list of addresses;
# defaults to ‘localhost’; use ‘*’ for all
# (change requires restart)
Save the changes and restart POSTGRES:
> sudo systemctl restart postgresql
Check that POSTGRES is listening:
> ss -nlt | grep 5432
This should return:
LISTEN 0 244 0.0.0.0:5432 0.0.0.0:* this is the config we are looking for
LISTEN 0 244 [::]:5432 [::]:*
Test the connection now by connecting to your DB from outside.
5.6.2 Configure the number of DB connections
When logged in the database, run the command:
# SHOW config_file;
Go to the config file and edit the max connections:
> sudo nano /etc/postgresql/12/main/postgresql.conf
Edit the max_connections parameter, set it to at least 300:
…
max_connections=100 -> change to at least 300
…
For further details regarding the number of connections see:
The connection count for 6 services running is 90. If you connect for debugging, that will go up fast.
Save and restart the database:
> sudo systemctl restart postgresql
6 Install the ERP
Setting up the ERP was greatly simplified. All the files needed can be compiled on the development machine then copied on the Linux machine.
Copy the ErpRelease folder contents (zip it first to allow faster transmission). Make the install-silent-linux-x64.sh file executable and then run it.
After running the installer, choose the environment and follow the installation instructions.
6.1.1 Debug the ERP server
If the applications don’t start, you can debug them by going in the ErpApiService folder and run:
> sudo dotnet ErpApiService.dll
7 System startup setup
7.1 ERP startup
The ERP system needs to be started every time the machine starts up. Add a record in the Startup Applications to run the *.sh file that starts the ERP server applications.
The file needs to be executable, so you need to chmod it either by making it executable from file explorer or by running (this should have been already done if you use the installer batch file):
> chmod +x /home/pos/ErpRelease/linux-x64/startup-no-restart-no-build-standalone.sh
In our case the Command parameter is:
/home/pos/ErpRelease/linux-x64/startup-no-restart-no-build-standalone.sh
7.2 Browser startup
If you have applications running on Linux machines, you might need to open the browser at system startup. To do this you can add to the Startup Applications the browser. Add entries for each application you want to start automatically.
If you need to start a browser you can use these values for the Command parameter:
Open Brave browser in KIOSK mode with a delay of 5 seconds on the main ERP screen:
bash -c “sleep 5 && brave-browser -kiosk –url http://192.168.1.10:4200”
Open Brave browser in KIOSK mode with a delay of 15 seconds on the Time Keeping screen:
bash -c “sleep 15 && brave-browser -kiosk –url http://192.168.1.10:4200/applications/human-resources/confirmation-screen”
Open Firefox browser in KIOSK mode with a delay of 15 seconds on the Time Keeping screen:
bash -c “sleep 15 && firefox –kiosk –url http://192.168.1.10:4200/applications/human-resources/confirmation-screen”
8 Seeding data
8.1 Install database migrations
Add the migrations for the main application and for all the plug-ins that have migrations in them.
Start the Package Manager Console. Select each project that contains migrations in its header and in Visual Studio’s main menu, select the proper connection string in the appsettings.Development.json file pointing to the correct database and run the update-database command.
8.2 Add Tenant and User data seeds
After the database migrations had been applied, run the ErpDataSeederApplication. Select the option to install a new Tenant. Enter a Tenant Name and continue. This will install a new Tenant, the administrator’s account and some default users and roles.
After installation, you should be able to login to the web UI with the tenant’s name and the administrator’s password. The default user name for the administrator account is Admin@<TenantName> and the password is Admin@<TenantName>.com
Switch to the user’s name & password login mode the first time you log in.
