Introduction

What is CircleCi and what is it used for?

CircleCi is a service that can help automate builds, tests and deployments and can be used for anything, from websites to mobile apps.

What is it used for? Typically it alerts you if your setup fails, whether it be during the build, testing or development stage. CircleCi does not have to all 3, it can be used for any, depending on your setup.

Prerequisites

• Sign up for a free account on CircleCi
• At this moment CircleCi only supports Github or Bitbucket accounts
• In the Projects settings page, choose the repo that you will set up for.
• Click setup.
• This will add a .circleci/config.yml file to your repo and will commit it. At the same time it will run the config.
• Congrats you have ran your first Ci.

Config

Here is my config

jobs:
  test:
    executor:
      name: node/default
      tag: '10.22'
    steps:
      - checkout
      - node/install-packages:
          pkg-manager: yarn
      - run:
          name: Run tests
          command: yarn test
  deploy:
    executor:
      name: node/default
      tag: '10.22'
    steps:
      - checkout
      - node/install-yarn
      - run:
          name: Install pm2
          command: sudo yarn global add pm2
      - run:
          name: Add Cloud server to known hosts
          command: |
            ssh-keyscan <ip of server> >> ~/.ssh/known_hosts
      - run:
          name: Deploy
          command: yarn deploy

version: 2.1
orbs:
  node: circleci/node@4.0.0
workflows:
  test:
    jobs:
      - test
      - deploy:
          filters:
            branches:
              only:
                - master
          requires:
            - test

Okay, let's go through this config.

version: 2.1
orbs:
  node: circleci/node@4.0.0
workflows:
  test-deploy:
    jobs:
      - test
      - deploy:
          filters:
            branches:
              only:
                - master
          requires:
            - test

I will be using config version 2.1 which supports orbs and workflows. An orb is like a preset which helps simplify the config file a lot. You can still work without orbs but you would have to set things up from scratch, like getting the image that you need, installing the packages, caching the packages, restore the packages. The purpose of caching the packages is to speed up the Ci for future builds.

I only have one workflow and that's to test my app and then deploy it. The deploy the job only happens if the master branch is pushed and the deploy job can only happen when the test job passes.

jobs:
  test:
    executor:
      name: node/default
      tag: '10.22'
    steps:
      - checkout
      - node/install-packages:
          pkg-manager: yarn
      - run:
          name: Run tests
          command: yarn test

With an orb, I can choose the node version with the executor setting. Without this, you would have to define the steps to set up the right node version with an nvm.

• checkout pulls your repo.
• node/install-packages installs your packages using npm but you can also specify the package manager you want to use. This really simplifies the need to install yarn manually and this command also simplifies the need to define your own save/restore cache commands.
• run the above steps were the build process. The next command is for running the tests that I have set up.

deploy:
    executor:
      name: node/default
      tag: '10.22'
    steps:
      - checkout
      - node/install-yarn
      - run:
          name: Install pm2
          command: sudo yarn global add pm2
      - run:
          name: Add Cloud server to known hosts
          command: |
            ssh-keyscan <ip of server> >> ~/.ssh/known_hosts
      - run:
          name: Deploy
          command: yarn deploy

Before setting up deployment, make sure that you set up ssh keys for circleci. I would follow the steps here under Settings or another good place setup ssh is from this article on Medium. I would follow the steps from 1-5, but I didn't create a new user for Ci on my server, I just added the ssh keys to my own current user. The important thing is to make sure that the ssh keys for Ci work by using

$ ssh circleci@my.droplet.ip -i ~/.ssh/id_rsa_circleci

With that all setup we can continue with the config.

• executor same as before, we're using the same node version.
• checkout pulls your repo.
• node/install-yarn we've already previously done the building but we just need to install yarn
• Install pm2 similar to the steps where we install pm2 on our local machine, but this time we translate this and install it on our Ci machine.
• ssh-keyscan <ip of server> >> ~/.ssh/known_hosts replace <ip of server> with the IP of your server. This step is most important otherwise pm2 will not be able to ssh into your server.
• yarn deploy deploys the app like we normally do locally.

Final Words

Congrats! And with this set up we have managed to:

• Add our project to CircleCi
• Setup our config to make Ci do want we want to do
• Run commands like running tests and deploy our app

It isn't easy getting Ci to do the things you want to do and there's a fair bit of trial and error. We can avoid wasting our precious credits by installing a `Circleci cli` which can help validate our config and run our jobs locally. You can find the documentation about what the cli can do here.

If you have homebrew installed

$ brew install circleci

If not

$ curl -fLSs https://raw.githubusercontent.com/CircleCI-Public/circleci-cli/master/install.sh | bash

And you can use commands like

$ circleci config validate .circleci/config.yml

To validate your config.

Hope this helps you kickstart your Ci journey.