Image
Steve
Steve Worley

Deploy to QuantCDN via CI

With the static movement there is an ever growing list of static site generators. These are software packages in many languages that provide theming capability and content managment via version control systems. At QuantCDN we use a number of these generators, docusaurus to build our docs pages and ReDoc to build our API docs just to name a few -- it is important to ensure the output of these tools can be deployed quickly and easily.

I love automation in all flavours, one of my favourites is automated testing via CI services which naturally lends itself to automated deployments. All of our docs repositories have automated tests and builds set up using CI pipelines. The QuantCDN edge is API driven so it was only a matter of time before we leveraged the API to automatically send the results directly to Quant!

Enter the QuantCLI tool!

With the Quant CLI tool we have a consistent way to interface with the QuantCDN API to send markup directly to the edge. It has simple configuration options and has been built in a way to allow you to easily incorporate it into your CI workflows, we have also made a docker image available which comes with all dependencies pre-installed.

In this article I would like to introduce how to use the CLI tool and how to incorporate it into your workflows. I'll be using CirlceCI for this demo -- stay tuned to the QuantCDN GitHub profile, I will be looking to have working examples for many popular cloud based CI services. With that out of the way, let's get started.

We will be walking through the Jekyll Example configuration and set up, for this demo we will assume that you have a running CI set up.

Add build caching to your configuration

Most cloud based CI services offer some level of build caching so that they can support a fan-in-fan-out workflow. This allow you to speed up your builds by having more workers available to run discrete commands. In the first example we will look to use an additional deploy step so that we can leverage the docker image to deploy our site. The additions we want to make to our CI configuration file is:

  • Add a caching step to our build configuration ensuring the build path is added to the cache
  • Add an additional job/stage to the pipeline
    • Restores the build cache
    • Deploy the build to QuantCDN

With CircleCI we need to add the following to our build step.

- save_cache:
    key: "app-{{ .Revision }}"
    paths:
      - _site

This will tell the Circle to cache our build with a unique key that will match app-<commit sha>. We can use this in our following deploy job to restore the cache and deploy our project.

Add the deploy job

Now that we have the build artefacts cached in Circle, we can create a deploy job. With this we can restore the cached assets and deploy them directly. As we develop the automated pipeline we can look to include additional jobs between build and deploy (maybe a test stage or two) and by using the artefacts we can reduce the resource requirements on the pipeline because each job won't have to build artefacts again.

deploy:
  docker:
    - image: quantcdn/cli
  steps:
    - restore_cache:
        keys: 
          - "app-{{ .Branch }}"
    - run:
        name: Deploy to QuantCDN
        command: quant deploy _site -c ${QUANT_CUSTOMER} -t ${QUANT_TOKEN} -p ${QUANT_PROJECT}

You can then wrap it up with the workflows definition:

workflows:
  version: 2
  build_and_deploy:
    jobs:
      - build
      - deploy:
          requires:
            - build
          filters:
            branches:
              only: master

And with that you're almost done! CirlceCI allows you to add environment variables which is a way to allow you to keep some values private, even when working with public opensource repositories -- as an aside Cirlce has some good resources on how to ensure your secrets are not leaked. Add your QuantCDN API details as environment variables, they can be found in your account from the dashboard.

It is important you don't leak your QuantCDN API token - this will give push access to your edge files please make sure to keep this safe!

Lets talk through the Quant CLI line -

quant deploy _site -c ${QUANT_CUSTOMER} -t ${QUANT_TOKEN} -p ${QUANT_PROJECT}

This will use the latest version of Quant CLI on dockerhub (which comes bundled with the latest version of QuantCLI from npm). It's the meat and potatoes for deploying to QuantCDN. This will recusrively scan the build directory with every file that is found it will push them to QuantCDN so that they can be served directly from the edge.

But I can't use the docker image - HELP!?

The docker image is a portable wrapper for the npm package, it configures node so that it can push large files (both volume and size!). If for whatever reason you can't use the docker image; you can always use the node package directly. This can be done either as a dependency on your node project or installing it globally.

npm i -g @quantcdn/quant-cli

If you install the CLI tool globally this will make the quant command available you can then run info, init or deploy. For more detail usage examples see the README or the docs page.

You can do this directly in CI as part of your automated process, with Circle it would look like:

deploy:
  docker:
    - image: cimg/node:latest
  steps:
    - run:
        name: Install QuantCDN CLI
        command: npm i -g @quantcdn/quant-cli
    - run:
        name: Deploy the build
        command: quant deploy <build dir> -c ${QUANT_CUSTOMER} -t ${QUANT_TOKEN} -p ${QUANT_PROJECT}

Very similar to using the QuantCDN CLI docker image, the only change is that you will need to manage the CLI dependency manually.

And thats it! That's how you can add QuantCDN deployments to your CI pipeline, checkout our example and stay tuned to our Github page for more. If you need a hand with your CI server leave a comment and we can help you out!