Deploy to production to Ubuntu server

This tutorial is designed to assist people who want to have a step-by-step guide to deploy the Lumber-generated back office to Ubuntu server.

Before following this tutorial, we recommend to read the Deploy to production how-to to create a Forest production environment.

Connect to your Ubuntu server using SSH

Before starting anything, you have to make sure you're able to connect to your server using SSH.

Command line
Output
ssh -i ~/.ssh/aws.pem ubuntu@ec2-18-204-18-81.compute-1.amazonaws.com

Copy the code of your back office to your remote server

There are many ways to copy the code of your back office to a remote server. For example, you can use rsync command, or use a versioning system like git.

We strongly advice to version the code of your back office server using git and host it to a private repository on Github, Bitbucket, Gitlab or other providers.

rsync

rsync is a utility for efficiently transferring and synchronizing files across computer systems, by checking the timestamp and size of files. It is commonly found on Unix-like systems and functions as both a file synchronization and file transfer program.

Rsync is typically used for synchronizing files and directories between two different systems. (source: wikipedia)

The syntax used is rsync OPTIONS SOURCE TARGET.

rsync -avz -e "ssh -i ~/.ssh/aws.pem -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null" --exclude=node_modules --exclude=.git --progress QuickStart ubuntu@ec2-18-204-18-81.compute-1.amazonaws.com:~/

In the example above, we use a SSH connection to transfer the file and we connect to the remote server using an identity_file (a private key).

Option

Description

-a

archive mode; same as -rlptgoD (no -H)

-v

increase verbosity

-z

compress file data during the transfer

-e

specify the remote shell to use

--exclude=PATTERN

exclude files matching PATTERN

--progress

show progress during transfer

Once done, you can find the code of your back office server on the home directory of your remote server.

Command line
Output
ssh -i ~/.ssh/aws.pem ubuntu@ec2-18-204-18-81.compute-1.amazonaws.com
ubuntu@ip-172-31-83-152:~$ cd Quickstart/
ubuntu@ip-172-31-83-152:~/QuickStart$ ls -l

git

First, you need to initialize a git repository for the code of your back office. From the directory of back office code, simply run:

git init

Then, you can add all the files and create your first commit.

git add .
git commit -am "First commit"

Finally, you can add your git remote and push the code on your favorite platform. Here, we're using Github.

git remote add origin git@github.com:ForestAdmin/QuickStart.git
git push -u origin master

Now, you can connect to your remote server using SSH and clone the repository using the HTTPS method.

Command line
Output
ssh -i ~/.ssh/aws.pem ubuntu@ec2-18-204-18-81.compute-1.amazonaws.com
git clone https://github.com/ForestAdmin/QuickStart.git

That's it. Your back office code is available on your remote server.

Command line
Output
ubuntu@ip-172-31-83-152:~$ cd QuickStart/
ubuntu@ip-172-31-83-152:~/QuickStart$ ls -l

Install dependencies

First, you have to make sure you have Node.js and NPM correctly installed on your server.

sudo apt update
sudo apt install nodejs npm

Then, you will be able to install all the dependencies listed on the package.json file.

npm install

Create the database

PostgreSQL

First, you need to install PostgreSQL:

sudo apt-get install postgresql postgresql-contrib

Then, you will be able to connect to the database server:

Command line
Output
sudo -u postgres psql

Now, we can export the database from your local environment (your computer) to import it to your Ubuntu server.

For security reason, we will not allow remote connections to this database. This is why transfer the database dump to the remote server using rsync.

From your computer:

PGPASSWORD=secret pg_dump -h localhost -p 5416 -U forest forest_demo --no-owner --no-acl -f database.dump
rsync -avz -e "ssh -i ~/.ssh/aws.pem -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null" --progress database.dump ubuntu@ec2-18-204-18-81.compute-1.amazonaws.com:~/

Then, we will create a new DB user and schema from the remote server:

sudo -u postgres psql
postgres=# CREATE USER forest WITH ENCRYPTED PASSWORD 'secret';
postgres=# CREATE DATABASE forest_demo;
postgres=# GRANT ALL PRIVILEGES ON DATABASE forest_demo TO forest;
postgres=# \q

And finally import the dump:

PGPASSWORD=secret psql -U forest -h 127.0.0.1 forest_demo < database.dump

That's it, your database is now fully imported.

Command line
Output
PGPASSWORD=secret psql -U forest -h 127.0.0.1 forest_demo
Command line
Output
forest_demo=> \d

Export the environment variables

You must export the environment variables FOREST_ENV_SECRET FOREST_AUTH_SECRET and DATABASE_URL. To do so, open and edit the file /etc/environment:

The FOREST_ENV_SECRET and FOREST_AUTH_SECRET environment variables will be given by Forest after creating a production environment from the interface. See how to get them here.

sudo vim /etc/environment
/etc/environment
PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games"
FOREST_ENV_SECRET=2417520743be37a9c5af198c018e0ddee9b7c41de1ccb8e76c9d027faa74059e
FOREST_AUTH_SECRET=Piq7a9Kv5anLbK4gj81rirsLhfaJ0pdL
DATABASE_URL=postgres://forest:secret@127.0.0.1/forest_demo

Then, you can restart your server to take these new variables into account or simply type:

for env in $( cat /etc/environment ); do export $(echo $env | sed -e 's/"//g'); done

Run your back office

From your back office directory, simply type:

Command line
Output
npm start

Congrats, your back office application is now running on production. But we strongly advice to continue following the next steps. If you chose not to do it, you can go back to your Forest interface to create a production environment. Check out here how to do it.

The back office server is by default listening on port 3000. Be sure you authorized the inbound traffic on this port or set up a web service (like NGINX) as a Reverse Proxy Server to use the port 80.

Manage Application with PM2

PM2 is a Production Runtime and 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 facilitate common Devops tasks. source: npmjs/pm2

Install PM2

sudo npm install pm2 -g

Run your back office using PM2

pm2 start bin/www

(Optional) Set Up Nginx as a Reverse Proxy Server

Now that your back office server is running and listening on localhost:3000, we will set up the Nginx web server as a reserve proxy to allow your back office users access it.

sudo apt install nginx

To do so, edit (with sudo access) the file located /etc/nginx/sites-available/default and replace the existing section location / by this one:

/etc/nginx/sites-available/default
location / {
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}

Then, restart nginx:

sudo systemctl restart nginx

That's it, your back office server is now listening on the port 80. Make sure your firewall allows inbound traffic from this port.

We strongly advice to configure HTTPS (port 443) on your back office service for security reason. http://nginx.org/en/docs/http/configuring_https_servers.html

Now you back office server is running on Heroku, you can go back to your Forest interface to create a production environment. Check out here how to do it.