POS OS - Setup Guide for Digital Ocean - Ubuntu Droplet

This guide will walk you through the process of setting up the POS OS software on a Digital Ocean Ubuntu droplet. It includes creating a new droplet and installing the required software on the droplet.

Prerequisites

• A Digital Ocean account. If you don't have one, sign up at https://www.digitalocean.com/ (opens in a new tab).
• A domain name (optional, but recommended for a production setup).

Step 1: Create a new Ubuntu droplet

1. Log in to your Digital Ocean account and navigate to the Droplets section.

2. Click the Create Droplet button.

3. Choose the appropriate Region according to your requirements.

4. From Choose an image section choose the "Ubuntu" distribution and select the desired "version" (e.g., Ubuntu 20.04 LTS).

5. Choose the appropriate droplet size according to your requirements. (choose minimum 2GB of RAM. Otherwise, you may face issues.)

6. Choose SSH Key or Password authentication

   • For SSH Key: Add your SSH key for secure access to the droplet. If you don't have an SSH key, follow this guide to create one: https://www.digitalocean.com/docs/droplets/how-to/add-ssh-keys/create-with-openssh/ (opens in a new tab)
   • For Password: Set a password for the root user. (Easiest and fastest way but this is not recommended for production setups).

7. Provide a hostname (or keep the random generated one) for your droplet and click Create Droplet.

8. Wait for the droplet to be created and for the ip address to be assigned.

And that's it! You have successfully created a new Ubuntu droplet on Digital Ocean (this is your cloud Ubuntu server).

Step 2: Access the droplet via SSH

1. Open a terminal/command promp/powershell on your local computer.
2. Connect to the droplet as a root user using SSH (SSH should be installed on your local computer):

ssh root@<droplet-ip-address>

replace <droplet-ip-address> with your droplet's IP address. For example: ssh root@127.0.0.1

3. When prompted, type "yes" to confirm the connection

   • If you are using SSH Key authentication, you will be prompted for your SSH key passphrase.
   • If you are using password authentication, you will be prompted for the password you set in Step 1.

4. You are now connected to the droplet via SSH and can run commands on the droplet (your cloud Ubuntu server) from your local computer's terminal.

Step 3: Install Node.js, npm, yarn and PM2

1. Run the following commands to install Node.js, npm, and yarn:

curl -sL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo apt install npm
sudo npm install -g yarn

Type Y and press enter when prompted.

You can change the version of Node.js by changing the version number in the first command (e.g., setup_14.x for Node.js 14). You can check (whether it is installed correctly) your Node.js version by running node -v and your npm version by running npm -v and your yarn version by running yarn -v.

2. Run the following command to install PM2:

sudo yarn global add pm2

Note: PM2 is a process manager for Node.js applications with a built-in load balancer. It allows you to keep applications alive forever, to reload them without downtime and to facilitate common system admin tasks. It's great for production environments, helps you to keep applications online 24/7, and can help you to build a resilient architecture with scalability. Know more about PM2 here (opens in a new tab).

Step 4: Install PostgreSQL Database

1. Run the following commands to install PostgreSQL:

sudo apt-get install -y postgresql postgresql-contrib

enter ok if prompted.

2. Create postgres user:

sudo -u postgres createuser --interactive

now enter the username that you want to set for the postgres user. (e.g., postgres)

3. Log in to the PostgreSQL shell:

sudo -u postgres psql

4. Change the password for the postgres user:

ALTER USER <username> WITH PASSWORD '<your_password>';

Replace <username> with the username you created in Step 5.3 and <your_password> with a secure password. (e.g., ALTER USER postgres WITH PASSWORD '123456';)

5. Exit the PostgreSQL shell:

\q

Step 5: Get the POS OS source code in your droplet

• Option 1: Clone the POS repository from GitHub

1. Upload the file that you have downloaded from Codecanyon to a repository of your github account

2. Access your droplet (follow step 2) and Clone your repository (that you have created in above step) to your droplet:

git clone https://github.com/your-repo/pos-os.git

Replace https://github.com/your-repo/pos-os.git with your POS repository's URL.

• Option 2: Get the file direct from your local computer to your droplet

1. Open a new separate terminal/command promp/powershell on your local computer.

2. Upload the zip file that you have downloaded from Codecanyon to your droplet (Ubuntu cloud server)

scp /<source-file-path> root@<droplet-ip-address>:/<destination-path>

Replace <source-file-path> with the path to the file on your local computer of the file you want to upload. It must be a zip file.

Replace <droplet-ip-address> with your droplet's IP address. Replace <destination-path> with the path to the folder on your droplet where you want to upload the file.

(e.g., to upload into the root folder of your droplet scp /home/username/pos-os.zip root@127.0.0.1:/root)

It will asked for your droplet password, enter your password and hit enter.

2. Access your droplet (follow step 2) and Install the unzip package on your droplet

sudo apt-get install unzip

3. Locate the file using cd command on your droplet and unzip it

unzip <Codecanyon-file-name>.zip

Replace <Codecanyon-file-name> with the name of the file you uploaded to your droplet (e.g., unzip pos-os.zip)

4. After unzipping, you will get a folder named POS-OS-application. Now you can sefely delete the zip file from your instance.

rm -r <Codecanyon-file-name>.zip

Step 6: Configure the backend (Express/Node.js)

1. Navigate to the backend folder: cd ../POS_OS_Backend

   replace ../ with the path to the backend folder on your droplet (e.g., cd POS-OS-application/POS_OS_Backend)

2. Install dependencies:

yarn

3. Configure the .env file according:

   a. Open/create the .env file:

   nano .env

   b. Copy the following content into the .env file:

   JWT_SECRET = <your_secret>
   DATABASE_URL = "postgresql://<postgres_username>:<postgres_user_password>@localhost:5432/<postgres_database_name>"
   HOST = <your_host>
   NODE_ENV = <environment_name>

   replace <your_secret> with a secure secret (e.g., JWT_SECRET = mysecret)

   replace <postgres_username> with the username, <postgres_user_password> with the password, <postgres_database_name> with the database name you created in Step 4. (e.g., postgresql://postgres:123456@localhost:5432/pos)

   replace <your_host> with the domain or IP address of your droplet (e.g., http://127.0.0.1).

   replace <environment_name> with the environment name (e.g., NODE_ENV = development). If use NODE_ENV = production then you have to set SSL certificate for your droplet. And edit the server.js file of your backend code.

   c. Save the file by pressing Ctrl + S, then close it by pressing Ctrl + X.

4. Run the migration by running the following command:

yarn prisma migrate dev

press enter when it asks for.

If auto seeding doewn't work, run the following command:

yarn prisma db seed

this will seed the database with the default data (with admin login name and password). If it doesn't run properly you can't login.

If it runs twice, it will throw an error. Then you can delete the migrations folder from /POS_OS_Backend/prisma/ and run the above commands again. Folder delete command: rm -r migrations

5. Navigate to the root of POS_OS_Backend where server.js is located and Start the backend server:

pm2 start server.js --name POS_backend

Here POS_backend is the name of the process that you want to give to the backend server. You can give any name you want.

Step 7: Configure the frontend (React.js)

1. Navigate to the frontend folder: cd ../POS_OS_Frontend

   replace ../ with the path to the frontend folder on your droplet (e.g., cd POS-OS-application/POS_OS_Frontend)

2. Install dependencies:

yarn

3. Configure the .env file according:

   a. Open/create the .env file:

   nano .env

   b. Copy the following content into the .env file:

   REACT_APP_API = 'http://<droplet-ip-address>:5000/'

   replace <droplet-ip-address> with the domain or IP address of your droplet (e.g., http://127.0.0.1:5000/v1/).

   c. Save the file by pressing Ctrl + S, then close it by pressing Ctrl + X.

4. Run the frontend server using PM2 process manager:

   pm2 start yarn --name POS_frontend -- start

   Here POS_frontend is the name of the process that you want to give to the frontend server. You can give any name you want.

   Change the backend file to accept the request from your frontend

   1. Nvigate to the backend folder: cd ../POS_OS_Backend
   2. Open the file app.js by using command nano app.js
   3. Find the variable allowedOrigins and add your frontend domain and port in the allowedOrigins variable as an array element.

   // holds all the allowed origins for cors access
    
   let allowedOrigins = [
   "http://localhost:3000",
   "http://localhost:5000",
   "http://<your_frontend_domain>:<your_frontend_port>",
   ];

   replace <your_frontend_domain> with your frontend domain and <your_frontend_port> with your frontend port (e.g., "http://127.0.0.1:3000").

   4. Save the file by pressing Ctrl + S, then close it by pressing Ctrl + X.

   5. Restart the backend server by running the following command:

   pm2 restart POS_backend

   replace POS_backend with the name of the process you gave to the backend server earlier in step 7.5

That's all you need to do to configure the backend and frontend. Now, you can access your POS software at http://<your_frontend_domain>:3000 (or your domain if you configured it).

Step 8: Point your domain to the instance (optional)

1. Log in to your domain registrar's control panel.
2. Set an A record for your domain, pointing it to your instance's IP address.

Now, your POS software should be accessible at http://<your_frontend_domain>:3000 (or your domain if you configured it). If you encounter any issues, make sure to check the logs and ensure that all services are running correctly.

Extras: for power users

Restart the server

If you change any file in the backend or frontend, you need to restart the server. To restart the server, run the following command:

pm2 restart <process_name>

replace <process_name> with the name of the process you gave to the backend or frontend server (e.g., pm2 restart POS_backend).

or you can restart all the processes by running the following command:

pm2 restart all

Stop the server

To stop the server, run the following command:

pm2 stop <process_name>

replace <process_name> with the name of the process you gave to the backend or frontend server (e.g., pm2 stop POS_backend).

or you can stop all the processes by running the following command:

pm2 stop all

Delete the server

To delete the server, run the following command:

pm2 delete <process_name>

replace <process_name> with the name of the process you gave to the backend or frontend server (e.g., pm2 delete POS_backend).

or you can delete all the processes by running the following command:

pm2 delete all

Monitor the server

To monitor the server and logs, run the following command:

pm2 monit

Check all the processes

To check all the processes, run the following command:

pm2 list

Update the Ubuntu system

If required to update the Ubuntu system, run the following command:

sudo apt update && sudo apt upgrade

If prompted to continue, press Y or select ok and then press enter.

Note: It's best practic to update the system before installing any software.

Update the Node.js

If required to update the Node.js, run the following command:

sudo npm cache clean -f
sudo npm install -g n
sudo n stable

Fix server related issues

If face any server related issue mostly you can fix it by using the mystreious magic method:

• Stop the server
• Then start the server again

Hope it may help you. Don't forget to start the frontend and backend server using pm2 process manager following the steps mentioned above.