POS OS
Aws

POS OS - Setup Guide for AWS - EC2 Ubuntu Instance

This guide will walk you through the process of setting up the POS OS software on a AWS EC2 Ubuntu Instance. It includes creating a new Instance and installing the required software on the instance.

Prerequisites

Step 1: Create a new EC2 Ubuntu instance

  1. Log in to your AWS account as a root user.

  2. Search for EC2 and navigate to the EC2 dashboard and click on Launch Instance.

  3. Provide the required folowing details to create a new instance:

    • Provide a name for your instance (e.g., pos os).
    • Select Ubuntu under Quick Start.
    • Select Ubuntu Server 22.04 LTS (HVM), SSD Volume Type from the list of available Amazon Machine Image (AMI).
    • Select the instance type (e.g., t2.small (1 vCPU, 2GiB Memory)). Minimum t2.small is recommended.
    • Select the number of instances (e.g., 1).
    • Select the key pair from dropdown, if not created earlier then click on create a new key pair and provide the following details:
      • Provide a name for the key pair (e.g., pos-os)
      • Select the key pair type (e.g., RSA)
      • Select Private key file format (e.g., .pem)
      • Click on Create key pair.
      • A file will be downloaded to your local computer. Save the file in a safe place. (e.g., pos-os.pem)

  4. Under Network Settings select Create security group or Select existing security group

    • If you select Create security group then tick the checkbox Allow SSH traffic from and select anywhere or My IP from the dropdown.

      If you select anywhere then you can access your instance from anywhere. If you select My IP then you can access your instance from your current IP address only.

    • If you select Select existing security group then select the security group from the dropdown.

  5. Configure the storage settings according to your needs. (e.g., 1 X 8 GiB - General Purpose SSD (gp2))

  6. Click on yellow Launch instance button and wait for the instance to be created.

  7. Open EC2 instance's port for Network traffic. To do this follow the steps below (by default, the port is open for SSH traffic only for security reasons):

    • Go to the Network & Security > Security Groups settings in the left hand navigation
    • Click on the Security group ID that you created in Step 1
    • Click on the Inbound rules tab and click on Edit inbound rules
    • Click on Add rule and select All traffic from the type dropdown, and select Anywhere IPv4 from the source dropdown. Then click on Save rules.

And that's it! You have successfully created a new EC2 Ubuntu instance on AWS (this is your cloud Ubuntu server).

Step 2: Access the instance via SSH

  1. Go to EC2 > Instances and click on the instance that you have created in Step 1.
  2. Click on Connect button and then select SSH client and follow the instruction there.

For example: to connect to your EC2 instance via SSH, locate where your key file was downloaded from terminal and then run the following command in your local computer's terminal:

chmod 400 <key_name>
ssh -i "<key_name>" ubuntu@<Public_IPv4_DNS>

replace <key_name> with the name of the key pair that you have created in Step 1.3 and <Public_IPv4_DNS> with the public IPv4 DNS of your instance. (e.g., ssh -i "pos-os.pem" ubuntu@ec2-13-127-77-90.ap-south-1.compute.amazonaws.com)

  1. When prompted, type "yes" to confirm the connection
  2. You are now connected to the instance via SSH and can run commands on the instance (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 if 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.

  1. 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.

  1. Create postgres user:
sudo -u postgres createuser --interactive

now enter the username that you want to set for the postgres user (e.g., postgres). Then enter y and press enter to confirm if prompted.

  1. Log in to the PostgreSQL shell:
sudo -u postgres psql
  1. 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';)

  1. Exit the PostgreSQL shell:
\q

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

  • 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 instance (follow step 2) and Clone your repository (that you have created in above step) to your instance:

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 instance

  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 instance (Ubuntu cloud server)

scp /<source-file-path> ubuntu@<Public_IPv4_DNS>:

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 <Public_IPv4_DNS> with the public IPv4 DNS of your instance.

(e.g., to upload into the root folder of your instance scp /home/username/pos-os.zip ubuntu@1ec2-13-127-77-90.ap-south-1.compute.amazonaws.com:)

It will upload the file to the root folder of your instance.

  1. Access your instance (follow step 2) and Install the unzip package on your instance
sudo apt-get install unzip
  1. Locate the file using cd command on your instance and unzip it
unzip <Codecanyon-file-name>.zip

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

  1. 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 instance (e.g., cd POS-OS-application/POS_OS_Backend)

  2. Install dependencies:

yarn

  1. 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 instance (Auto-assigned IP address) (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 instance. 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.

  2. 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

  1. 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 instance (e.g., cd POS-OS-application/POS_OS_Frontend)

  2. Install dependencies:

yarn

  1. 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://<Auto-assigned_IP_address>:5000/'

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

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

  2. Run the frontend server using PM2 process manager:

    pm2 start yarn --name POS_frontend -- start

    Wait until the build is completed. Usually, it takes 2-5 minutes to get ready the Frotend. 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://<Auto-assigned_IP_address>:<your_frontend_port>",
];

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

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

    2. 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://<Auto-assigned_IP_address>: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://<Auto-assigned_IP_address>: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.


You have successfully deployed your app to the WORLD
🎉 Congratulations! 🎉

POS OSDigital Ocean