Deployment

This guide discusses how to deploy a project, that uses Onboardbase to manage its secrets.

Provisioning a VM for deployment

📘

TIP

You can authenticate the CLI with Environment variables.
Supported environment variables are:

  • ONBOARDBASE_TOKEN - A service token
  • ONBOARDBASE_PROJECT - an onboardbase project name
  • ONBOARDBASE_ENVIRONMENT - an environment in the specified project

Setting up a DO Droplet and authenticating it with SSH keys

In this section, we will set up a Digital Ocean droplet to deploy our project. We assume that you have already created a Droplet; if not, please do that here

With your Droplet running, ensure that you authenticate it with SSH and also have access to the private key. Check here to create and add an SSH key for your Droplet.

Setting up an EC2/Lightsail instance and authenticating it with SSH keys

For EC2 users, who also have an EC2 instance running, use this guide to create one if you do not have any. Also, authenticate your EC2 instance using SSH, ensuring that you have access to the public key. If your instance does not have any ssh key attached, follow this instruction

Setting up a Compute Engine instance and authenticating it with SSH keys

GCP users can use a running VM instance or follow this guide to create one. Also, the instance should have a public SSH key attached to it. Use this guide to add a public SSH Key.

TLDR; For all the Cloud Providers, aside from attaching a public SSH key to the server, do note, that the private key is required during the CI/CD process.

Generate service token

From your Onboardbase, go to the account page, click on Generate service tokens and give it a name (based on the service you want to use it for). Copy the generated service token and store it as a config variable for the service.

Setting up the VM

Install Nginx

Login to your VM instance using SSH - via web or from a connected machine.

Install Nginx with:

sudo apt update
sudo apt install nginx

Enter the machine's IP address in a browser to see the default nginx page.

The default page is stored at /var/www; we would be pushing the final build of the app into this directory.

Pull the code into the VM

To build the project, we have to pull the code into the VM, and we will use git for this.

Firstly, we will create a new folder and use the git remote URL to pull the project.

mkdir ~/app
cd ~/app
git clone [GIT_REMOTE] ./

Install Onboardbase CLI

# Download the deb
wget https://onboardbase-cli.fra1.digitaloceanspaces.com/apt/onboardbase-latest.deb

# install
sudo dpkg -i ./onboardbase-latest.deb

# Verify
onboardbase --version

Authenticate the VM

After successful installation, authenticate the CLI by running:

onboardbase login

Choose N to not open the authentication URL in a browser, which will

Copy the authentication URL, paste it into a browser on your host machine, enter your email, and finalize it by clicking on the link sent to your email.

Setting up the VM

After authentication, change the directory to the project directory.

cd ~/app

Then run:

onboardbase setup

This would ask you for the project, then the environment secrets that you want to pull into the project, then prompt you if you want to add the file to .gitignore, choose N as the development environment should have added it already.

At the end of the process, an .onboardbase.yaml file should have been created.

Test/Manual Build

To manually build the project from the project directory in the VM run:

# Go to the project folder
cd ~/app

# Cleanup previous build
rm -rf ./build

# Run the managed build process
yarn build

# Clean up the deployment folder
rm -rf /var/www/*

# Copy new build file to the deployment folder
cp ./build/* /var/www

We also need to run the above command when deploying the application from a CI/CD server.

Getting ready for CI/CD Providers

To use Onboardbase CLI in your CI/CD process, ensure that you have a CLI authentication token available immediately after authentication.

Since a CI/CD server is automated and can not open a browser or confirm an email on a human behalf, the easiest way to get a CLI token is to authenticate a development environment that you work from by running onboardbase login, and after login, run onboardbase config:get-token command to list all the auth tokens attached to the current machine. Copy the appropriate token and keep it somewhere safe.

Onboardbase supports ENV Configurations - reading project and environment configuration from Environment Variables to make deployment easier.

An environment can set the project to read from by setting an ONBOARDBASE_PROJECT in the env and ONBOARDBASE_ENVIRONMENT environment for an environment inside of the project.

Follow the step for your CI Provider to set project secrets/environment variables and ensure these values are available:

  • ONBOARDBASE_PROJECT The Onboardbase project name
  • ONBOARDBASE_STAGING_ENVIRONMENT The name of the staging environment in the Onboardbase project
  • ONBOARDBASE_PRODUCTION_ENVIRONMENT The name of the production environment in the Onboardbase project
  • ONBOARDBASE_TOKEN A CLI token, use Onboardbase config:get-token to see your tokens.
  • STAGING_SSH_HOST The staging VM ssh host address
  • PRODUCTION_SSH_HOST The production VM ssh host address.

With this, the setup process is redundant for CI/CD servers.

Deploying through CI/CD

We need a sequence of commands after connecting directly to the VM HOST through SSH to deploy.

cd ~/app && git fetch && git checkout dev && git pull origin dev && yarn  && rm -rf ./build && yarn build && rm -rf /var/www/* && cp ./build/* /var/www

We don't need to run or set up Onboardbase CLI in the CI/CD process since we already have it installed while setting up the VM.

GitlabCI/CD

stages:
  - deploy

deploy_to_dev:
  stage: deploy
  image: tetraweb/php
  before_script:
  - 'which rsync || ( apt-get update -y && apt-get install rsync -y )'
  - 'which ssh-agent || ( apt-get update -y && apt-get install openssh-client -y )'
  - eval $(ssh-agent -s)
  - ssh-add <(echo "$STAGING_SSH_KEY")
  - mkdir -p ~/.ssh
  - echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config
  script:
  - ssh $STAGING_SSH_HOST "cd ~/app && git fetch && git checkout dev && git pull origin dev && yarn  && rm -rf ./build && yarn build && rm -rf /var/www/* && cp ./build/* /var/www"
  only:
  - dev


deploy_to_production:
  stage: deploy
  image: tetraweb/php
  before_script:
  - 'which rsync || ( apt-get update -y && apt-get install rsync -y )'
  - 'which ssh-agent || ( apt-get update -y && apt-get install openssh-client -y )'
  - eval $(ssh-agent -s)
  - ssh-add <(echo "$PRODUCTION_SSH_KEY")
  - mkdir -p ~/.ssh
  - echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config
  script:
  - ssh $PRODUCTION_SSH_HOST "cd ~/app && git fetch && git checkout dev && git pull origin dev && yarn  && rm -rf ./build && yarn build && rm -rf /var/www/* && cp ./build/* /var/www"
  only:
  - master

CircleCI

version: 2
jobs:
  staging:
    docker:
      - image: cimg/base:2021.04
    steps:
      - restore_cache:
          key: dependency-cache-{{ checksum "yarn.lock" }}
      - run: 
        name: install-rsync
        command: 'which rsync || ( apt-get update -y && apt-get install rsync -y )'
      - run:
          name: install-ssh 
          command: 'which ssh-agent || ( apt-get update -y && apt-get install openssh-client -y )'
      - run:
          name: setup-ssh
          command: 'eval $(ssh-agent -s) && ssh-add <(echo "$STAGING_SSH_KEY") && mkdir -p ~/.ssh && echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config'
      - run:
          name: install-onboardbase
          command: 'wget https://onboardbase-cli.fra1.digitaloceanspaces.com/apt/onboardbase-latest.deb && sudo dpkg -i ./onboardbase-latest.deb && onboardbase --version'
      - run:
          // Authenticate the onboardbase
          name: authenticate-onboardbase
          command: 'onboardbase config:set-token $ONBOARDBASE_TOKEN --scope (pwd)'
      - run: 
          // Setup the onboardbase
          name: verify-onboardbase-project-and-environment
          command: 'echo $ONBOARDBASE_PROJECT && echo $ONBOARDBASE_ENVIRONMENT'
      - run:
          name: 
      - run:
          // Setup the project
          name: build-deploy
          command: 'ssh -o "StrictHostKeyChecking no" $STAGING_SSH_HOST "cd ~/app && git fetch && git checkout dev && git pull origin dev && yarn  && rm -rf ./build && yarn build && rm -rf /var/www/* && cp ./build/* /var/www'

  production:
    docker:
      - image: cimg/base:2021.04
    steps:
      - restore_cache:
          key: dependency-cache-{{ checksum "yarn.lock" }}
      - run: 
        name: install-rsync
        command: 'which rsync || ( apt-get update -y && apt-get install rsync -y )'
      - run:
          name: install-ssh 
          command: 'which ssh-agent || ( apt-get update -y && apt-get install openssh-client -y )'
      - run:
          name: setup-ssh
          command: 'eval $(ssh-agent -s) && ssh-add <(echo "$PRODUCTION_SSH_KEY") && mkdir -p ~/.ssh && echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config'
      - run:
          name: install-onboardbase
          command: 'wget https://onboardbase-cli.fra1.digitaloceanspaces.com/apt/onboardbase-latest.deb && sudo dpkg -i ./onboardbase-latest.deb && onboardbase --version'
      - run:
          // Authenticate the onboardbase
          name: authenticate-onboardbase
          command: 'onboardbase config:set-token $ONBOARDBASE_TOKEN --scope (pwd)'
      - run: 
          // Setup the onboardbase
          name: verify-onboardbase-project-and-environment
          command: 'echo $ONBOARDBASE_PROJECT && echo $ONBOARDBASE_ENVIRONMENT'
      - run:
          name: 
      - run:
          // Setup the project
          name: build-deploy
          command: 'ssh -o "StrictHostKeyChecking no" $PRODUCTION_SSH_HOST "cd ~/app && git fetch && git checkout dev && git pull origin dev && yarn  && rm -rf ./build && yarn build && rm -rf /var/www/* && cp ./build/* /var/www'

workflows:
  version: 2

  staging:
    jobs:
      - staging:
          filters:
            branches:
              only: dev
  production:
    jobs:
      - production:
          filters:
            branches:
              only: main

TravisCI

// configure which branches to run
branches:
  // whitelist
  only:
    - dev

// declare your environment variables
env:
  // global will stay the same across all matrix possibilities (will not create additional combinations to run)
  global:
    - ONBOARDBASE_TOKEN: $ONBARDBASE_TOKEN
    - ONBOARDBASE_ENVIRONMENT: $ONBOARDBASE_ENVIRONMENT
    - ONBOARDBASE_PROJECT: $ONBOARDBASE_PROJECT

install:
  // Install onboardbase CLI
  - which rsync || ( apt-get update -y && apt-get install rsync -y )
  - which ssh-agent || ( apt-get update -y && apt-get install openssh-client -y )
  - onboardbase --version

deploy:
  - provider: script
    script: ssh -o "StrictHostKeyChecking no" $PRODUCTION_SSH_HOST "cd ~/app && git fetch && git checkout dev && git pull origin dev && yarn  && rm -rf ./build && yarn build && rm -rf /var/www/* && cp ./build/* /var/www
    on:
      branch: master
  - provider: script
    script: ssh -o "StrictHostKeyChecking no" $PRODUCTION_SSH_HOST "cd ~/app && git fetch && git checkout dev && git pull origin dev && yarn  && rm -rf ./build && yarn build && rm -rf /var/www/* && cp ./build/* /var/www
    on:
      branch: dev

GitHub Actions

// This is a workflow to deploy the api part of this project to docker

name: Deploy React App

on:
  push:
    branches:
      // Only run when the release branch receives an update.
      - "main"

env:
  ONBOARDBASE_PROJECT: ${{ secrets.ONBOARDBASE_PROJECT }}
  ONBOARDBASE_ENVIRONMENT: ${{ secrets.ONBOARDBASE_ENVIRONMENT }}
  ONBOARDBASE_TOKEN: ${{ secrets.ONBOARDBASE_TOKEN }}

jobs:
  setup-build-deploy:
    name: Setup, Build, and Deploy
    runs-on: ubuntu-latest
    steps:
      // Configure docker to use the gcloud command-line tool as a credential helper
      - run: |-
          which rsync || ( apt-get update -y && apt-get install rsync -y ) \
          which ssh-agent || ( apt-get update -y && apt-get install openssh-client -y ) \
          eval $(ssh-agent -s) \
          ssh-add <(echo "$PRODUCTION_SSH_KEY") \
          mkdir -p ~/.ssh \
          echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config

      
      - name: Deploy
        run: |-
          ssh -o "StrictHostKeyChecking no" $PRODUCTION_SSH_HOST "cd ~/app && git fetch && git checkout dev && git pull origin dev && yarn  && rm -rf ./build && yarn build && rm -rf /var/www/* && cp ./build/* /var/www"