s-lyn/MANUAL.md

## MANUAL.md

      
    Raw
  

              MANUAL.md
            
          
    Deploy nodejs app with gitlab.com and pm2

This manual is about setting up an automatic deploy workflow using nodejs,
PM2, nginx and
GitLab CI. It is tested on:

Target server: Ubuntu 16.04 x64. This is suitable for Ubuntu 14.x.
Windows 10 on my PC to work.

I use Alpine Linux in Docker container (gitlab) to speed up deployment.
What do we need:

Account on gitlab.com
New virtual server with Ubuntu 16.04 x64 (or 14.x) to run application
(i will call it the "target server")

Configure target server

1. Create new sudo-user

Login with SSH user "root " and run:
adduser ubuntu
usermod -aG sudo ubuntu
To check sudo access run:
su ubuntu
sudo ls -la /root
2. Install nodejs and npm

You can find official instruction
here.
For Ubuntu 16.04 run:
curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
sudo apt-get install -y nodejs
To check an installation run:
node -v
npm -v
3. Install process manager pm2

PM2 is a beautiful production process manager for nodejs. It will observe, log and
automatically restart your application if it fall. Run now:
sudo npm install -g pm2@latest
To enable auto start pm2 on reboot run:
pm2 startup
then (!important) follow the instructions on your screen (run displayed command).
4. Install git

sudo apt-get install git -y
If you haven't deploy git keys yet, you should run:
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
This command will generate private (/home/ubuntu/.ssh/id_rsa) and public
(/home/ubuntu/.ssh/id_rsa.pub) key. Print public key:
cat /home/ubuntu/.ssh/id_rsa.pub
copy it clipboard and paste to gitlab (Repo settings / Tab "Repository" / Deploy Keys).
Check ssh access to repository:
ssh -T git@gitlab.com
On the question "The authenticity of host...?" answer "yes".
If all is okay, you should see string like "Welcome to GitLab, yourUsername!".
5. Generate SSH keys for current server

Now we should generate SSH keys to access current server without password.
Run next command again, but set file path to /home/ubuntu/access:
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
This command will generate private (/home/ubuntu/access) and public (/home/ubuntu/access.pub) key.
Move new generated key to authorized_keys:
cat /home/ubuntu/access.pub >> ~/.ssh/authorized_keys
You must copy and save private key on your computer. To print this key on screen use:
cat ~/access
6. Install nginx

sudo apt-get install nginx -y
sudo rm /etc/nginx/sites-enabled/default
Open nginx config:
sudo nano /etc/nginx/sites-available/app
and replace it with:
server {
  listen 80;
  server_name app;
  location / {
    proxy_set_header  X-Real-IP  		$remote_addr;
	proxy_set_header  X-Forwarded-For 	$proxy_add_x_forwarded_for;
    proxy_set_header  Host       		$http_host;
	proxy_set_header  X-NginX-Proxy 	true;
    proxy_pass        http://127.0.0.1:3000;
	proxy_redirect off;
    proxy_buffering off;
  }
}
Then run:
sudo ln -s /etc/nginx/sites-available/app /etc/nginx/sites-enabled/app
sudo systemctl restart nginx
# Note: for Ubuntu 14.x run instead: sudo service nginx restart
And check nginx status (it should be "active"):
sudo systemctl status nginx
Configure deployment with Gitlab CI

1. Create file ecosystem.config.jsin root directory of your project:

// Target server hostname or IP address
const TARGET_SERVER_HOST = process.env.TARGET_SERVER_HOST ? process.env.TARGET_SERVER_HOST.trim() : '';
// Target server username
const TARGET_SERVER_USER = process.env.TARGET_SERVER_USER ? process.env.TARGET_SERVER_USER.trim() : '';
// Target server application path
const TARGET_SERVER_APP_PATH = `/home/${TARGET_SERVER_USER}/app`;
// Your repository
const REPO = 'git@gitlab.com:yourUsername/test-server.git';

module.exports = {
  /**
   * Application configuration section
   * http://pm2.keymetrics.io/docs/usage/application-declaration/
   */
  apps: [
    {
      name: 'testApp',
      script: 'index.js',
      env: {
        NODE_ENV: 'development'
      },
      env_production: {
        NODE_ENV: 'production',
        PORT: 3000
      }
    }
  ],

  /**
   * Deployment section
   * http://pm2.keymetrics.io/docs/usage/deployment/
   */
  deploy: {
    production: {
      user: TARGET_SERVER_USER,
      host: TARGET_SERVER_HOST,
      ref: 'origin/master',
      repo: REPO,
      ssh_options: 'StrictHostKeyChecking=no',
      path: TARGET_SERVER_APP_PATH,
      'post-deploy': 'npm install --production'
        + ' && pm2 startOrRestart ecosystem.config.js --env=production'
        + ' && pm2 save'
    }
  }
};
2. Add secret variables in gitlab:

Go to gitlab.com -> Your project -> "Settings" -> "CI/CD" -> "Secret variables".
Add some variables:


Variable
Description


TARGET_SERVER_HOST
Target server host like 127.0.0.1 or your.host.com


TARGET_SERVER_USER
SSH username for login. Example ubuntu


TARGET_SERVER_SECRET_KEY_BASE64
Base64 encoded private RSA key to login target server. Make it protected


3. Create file .gitlab-ci.yml in root directory of project:

image: keymetrics/pm2:6

stages:
  - deploy

deploy_prod:
  stage: deploy
  script:
    - echo "====== Deploy to production server ======"
    - apk update && apk upgrade
    - apk add git openssh bash
    # Add target server`s secret key
    - mkdir ~/.ssh
    - echo $TARGET_SERVER_SECRET_KEY_BASE64 | base64 -d > ~/.ssh/id_rsa
    - chmod 700 ~/.ssh && chmod 600 ~/.ssh/*
    - echo "Test ssh connection"
    - ssh -o StrictHostKeyChecking=no -T "ubuntu@$TARGET_SERVER_HOST"
    # Delploy
    - echo "Setup tagget server directories"
    - pm2 deploy ecosystem.config.js production setup 2>&1 || true
    - echo "make deploy"
    - pm2 deploy ecosystem.config.js production
  environment:
    name: deploying
  only:
  - master
If all is okay, your project will be automatically deployed every push and merge to master branch.
Variable	Description
TARGET_SERVER_HOST	Target server host like `127.0.0.1` or `your.host.com`
TARGET_SERVER_USER	SSH username for login. Example `ubuntu`
TARGET_SERVER_SECRET_KEY_BASE64	Base64 encoded private RSA key to login target server. Make it protected