Tech, Cloud and Programming

Zola, Github Pages and CloudFlare

2022-01-26 | zola github cloudflare

A Blog..

It's time to start sharing again interesting things on my own website. A.k.a. blogging, but then how?

The important things for me:

  • Full control ,not a 3rd service like medium
  • Open source products
  • Easy to write and quick to publish
  • Avoid html/css/js as much as i can while writing
  • Fast & Responsive website
  • Free (very cheap)

I decided on a markdown based static website generator. I got some bad experiences with Hugo and Jekyll (Ruby😳) from previous projects. The final decision was between VuePress and Zola. Having worked with VuepPess a lot, i choose the new technology, Zola.

Zola

Zola is a "blazing" fast generator written in Rust. It's builds the whole website under a second. With Content in Markdown, templates in HTML with Tera

Created a quick demo

zola init myblog

Answer a few questions 

> What is the URL of your site? (https://example.com):
> Do you want to enable Sass compilation? [Y/n]:
> Do you want to enable syntax highlighting? [y/N]:
> Do you want to build a search index of the content? [y/N]:

The basic layout is then

├── config.toml
├── content/
│   └── blog/
│       ├── _index.md
│       ├── first.md
│       └── second.md
├── sass/
├── static/
├── templates/
│   ├── base.html
│   ├── blog-page.html
│   ├── blog.html
│   └── index.html
└── themes/

It has a local webserver for live testing/editting zola serve and open it at: http://127.0.0.1:1111

Add a theme of your linking from the gallery. I'm using codinfox-zola. With some modifications

Github repository

To store the website i use GitHub. With private repo's on the free tier it's easy to use. I added a .gitignore to avoid any locally generated content to be uploaded.

public/

CloudFlare

CloudFlare is a CDN with a free-tier, that's very generous and more then enough for a personal blog. I registered by Domain with CloudFlare, they are one of the cheapest registrars and started to setup.

Next i wanted to use Pages. It's a website hosting service that combines static hosting with fast interactive software. This can be compared with AWS S3 and Lambda, but then all in 1 "easy" to use interface. Besides static generators it also supports react,next.js and others.

There is Zola support, so i thought that's easy: connect CloudFlare with Github and let it build. But the build image is missing the zola binary. :( I notified cloudflare, but i went for a workaround

GitHub Pages

I could choose AWS S3, but then you might run into some costs. My accounts all are out of free-tier. So i went for GitHub pages. A simple/free way to have a public repo as webserver.

  1. Create a repo named: username.github.io
  2. Upload at least a index.html to the main branch
  3. Open https://username.github.io

To use it with Zola, run zola build and copy the output in the public\ directory to the username.github.io repo and push to the main branch Your mini website should be reachable now.

Your own domain name

While the github.io domain isn't that bad, we want to use our own registered domain. CloudFlare makes this very easy.

  • Open your domain
  • Edit DNS
  • Create record blog as CNAME and have a target: username.github.io, make sure the proxy switch is enabled.

Now, after the dns is available you can go to https://blog.yourdomain.com. Unfortunately this gives an error page. This comes from github who doesn't know which page to load. The solution is to add a special file in the root directory. Github

For Zola, create a file named CNAME with content: blog.yourdomain.com and place it in the static directory. Every time you build zola the file is copied to the public/ directory and makes it work. Deploy the website and test it again.

CloudFlare is a caching proxy, it keeps pages a certain amount time in it's memory before it gets a new version from the server. To force this, run a purge in cloudflare.

Automation

When we push to the main branch in our website repo do the following actions:

  1. Test and Build the zola website
  2. Upload the public\ directory to the username.github.io repo
  3. Purge the cloudflare cache

Create a github workflow to run these actions

Secrets

We need credentials to talk with github and cloudflare. There are stored in github secrets

To create the cloudflare token, go here.

Create Token

  • Name: github purge token
  • Type: Custom
  • Permissions: Zone , Cache Purge
  • Zone Resources: include, specific zone, yourdomain.com

Safe the token in the github secret: CLOUDFLARE_TOKEN

Find the Zone Id in the zone page and store in CLOUDFLARE_ZONE

Github Personal Access Token.

  • Click your account
  • Settings -> Developer Settings -> Personal access token
  • Generate
  • Expire: 6months / or more
  • Permissions: Repo: status, Repo_deployment, public_repo

Save the token in the secret: PUBLIC_TOKEN

Create the workflow file to combine all .github/workflows/main.yml

on: push
jobs:
  build_and_deploy:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - name: 'checkout'
        uses: actions/checkout@v2
      - name: 'build and deploy'
        uses: shalzz/[email protected]
        env:
          PAGES_BRANCH: master
          BUILD_DIR: .
          TOKEN: ${{ secrets.PUBLIC_TOKEN }}
          REPOSITORY: jverhoeks/jverhoeks.github.io
      - name: Purge cache
        uses: jakejarvis/cloudflare-purge-action@master
        env:
          # Zone is required by both authentication methods
          CLOUDFLARE_ZONE: ${{ secrets.CLOUDFLARE_ZONE }}
          CLOUDFLARE_TOKEN: ${{ secrets.CLOUDFLARE_TOKEN }}

Push a change to your website repo main branch and watch the actions tab in the github website. You can see the steps checkout, build and deploy, purge cache and view the result. All should be right and the website will the updated automatic.

This was the first article, time for some more. 😁

Other Posts