QuantCDN static site construction banner

Static site generators everywhere

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 management 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 flavors, and one of my favorites 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 and assets 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 CircleCI 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 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
    • Deploys 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 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 artifacts 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 artifacts, we can reduce the resource requirements on the pipeline because each job won't have to build artifacts 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! CircleCI allows you to add environment variables which is a way to allow you to keep some values private, even when working with public open source repositories -- as an aside Circle 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!

Let's 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 Docker Hub (which comes bundled with the latest version of QuantCLI from npm). It's the meat and potatoes for deploying to QuantCDN. This will recursively scan the build directory with every file that is found and 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 detailed 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}

This is very similar to using the QuantCDN CLI docker image; the only change is that you will need to manage the CLI dependency manually.

And that's 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, contact us and we can help you out!

About QuantCDN

Quant is a global static edge; a CDN combined with static web hosting. We provide solutions to help make WordPress and Drupal sites static, as well as support for all popular static site generators.