Host your static website 100% free with jekyll, gitlab pages & cloudflare / 17 May 2019 / Author: Haim Ari

    Estimated read time: 5 minutes

    These days it is easier than ever to build and host a static website without any cost.

    What is a static website ?

    From Techterms

    A static website contains Web pages with fixed content. Each page is coded in HTML and displays the same information to every visitor. Static sites are the most basic type of website and are the easiest to create. Unlike dynamic websites, they do not require any Web programming or database design. A static site can be built by simply creating a few HTML pages and publishing them to a Web server.

    What is a dynamic website ?

    From: Techterms

    Dynamic websites contain Web pages that are generated in real-time. These pages include Web scripting code, such as PHP or ASP. When a dynamic page is accessed, the code within the page is parsed on the Web server and the resulting HTML is sent to the client’s Web browser.

    What is a “Static site generator”

    From creativebloq

    static site generators are command-line tools that shift the creation of the final HTML page forward from the point the user requests it to the point you write the content. When you make an update, you build the new page, which can then be served as-is to every user who requests it.

    Ok, So which one should you use ?

    Well, it depends, but if you just want to host a Blog / Vlog / Website with static content, then it is possible to do that without a server, this makes things simpler, reduces the number of components you need to install, keeps your content portable and allows you to focus just on content.

    Even if you want to have a “Search” function on you website, you do not need a server (See the search bar at the top of the page ? yes, no server.)

    By the end of this tutorial you should have a gitlab pages website, and a gitlab ci pipeline that generate your static content and deploys it.

    Pipeline

    How do i get started ?

    There are so many guides on the web, and this could be confusing… so in this post I’ll explain how this website works.

    We will use the following to build, deploy, and optimize the speed of our website:

    Jekyll has great documentation for building your static website so i’m not going to cover that here

    Build with Jekyll:

    I’ve worked with hugo and other static site generators, and finally found that Jekyll works best for me. It does not matter which one you use, but you will have to adapt the Gitlab CI/CD pipeline to your choice.

    In this tutorial we will use Jekyll as our static website generator.

    First build your website locally using:

    jekyll build
    

    Then start a local server for development

    jekyll serve
    

    You should see an output similar to this:

    Configuration file: /jekyll/yoursite/_config.yml
                Source: /jekyll/yoursite
           Destination: /jekyll/yoursite/_site
     Incremental build: disabled. Enable with --incremental
          Generating... 
                        done in 1.699 seconds.
     Auto-regeneration: enabled for '/jekyll/yoursite'
        Server address: http://127.0.0.1:4000
      Server running... press ctrl-c to stop.
    
    

    browse your local server and check that everything works as expected.

    http://127.0.0.1:4000
    

    Go, to gitlab.com and create a free account if you don’t already have one. Gitlab also has great documentation for gitlab pages.

    Create your gitlab project

    Create a private gitlab project, and add your jekyll project to it using git or your IDE.

    Create .gitlab-ci.yml

    This is the file that instructs gitlab to run your pipeline, every time you commit and push code to your project (change configuration, add a new post…) A pipeline will run according to this file configuration. Here is how i use it:

    image: ruby:2.3
    stages:
      - test
      - deploy
      - clear-cache
    
    variables:
      JEKYLL_ENV: production
      LC_ALL: C.UTF-8
    
      IMAGE_TAG: $CI_REGISTRY_IMAGE:curl
    
      CLOUDFLARE_URL: https://api.cloudflare.com/client/v4/zones/$cloudflare_zone_id/purge_cache
      EMAIL: "X-Auth-Email: $cloudflare_email_account"
      AUTH:  "X-Auth-Key: $cloudflare_api_key"
      CONTENT: 'Content-Type: application/json'
    
    
    before_script:
      - bundle install
    
    test:
      stage: test
      script:
      - bundle exec jekyll build -d test
      artifacts:
        paths:
        - test
      except:
      - master
    
    pages:
      stage: deploy
      script:
      - bundle exec jekyll build -d public
      artifacts:
        paths:
        - public
      only:
      - master
    
    clear-cache:
      before_script:
      - ''
      image: $IMAGE_TAG
      stage: clear-cache
      script:
      - curl -X POST "${CLOUDFLARE_URL}" -H "${EMAIL}" -H "${AUTH}" -H "${CONTENT}" --data '{"purge_everything":true}'
      only:
      - master
      dependencies: []
    

    Now lets break this down stage by stage:

    (For more details on gitlab ci read the GitLab CI/CD Pipeline Configuration Reference)

    Pipeline

    This pipeline is very simple and only has 2 important stages (the 3rd stage ‘clean-cache’ is optional)

    • test
    • pages(This is an internal gitlab stage)

    The test stage simply validate the jekyll build, if it does not pass, the deployment will not take place. it deploys the content to /test path

    The pages stage gitlab simply builds your project and set the output path.

    bundle exec jekyll build -d public
    

    in other words it builds your static website and using an internal gitlab method to only expose the artifacts (your html) and not your code by placing it at the ‘public’ path. This is the reason your project does not need to be public, and you only expose the final static content and not your code.

    What this code is doing is creating a job called pages telling the Runner to deploy the website artifacts to a public path, whenever a commit is pushed only to the master branch.

    You can read this great gitlab pages tutorial which has some useful links for themes, bundler information and more.

    So what we have done so far ?
    • created a local development & server using jekyll
    • created a gitlab project (repository) with our raw code.
    • created a gitlab stage to build and generate the static content
    • created another stage to deploy that content and expose it publicly as our website.

    So if your pipeline completed successfully, you should be able to access your website now at:

    https://mynamespace.gitlab.io
    

    You can also set up a custom domain and add SSL to your gitlab pages. This is all covered here

    What about CDN ?

    The advantages i found in using Cloudflare are:

    1. No need to update SSL
    2. if gitlab pages service is down, the site will still be online for users.
    3. improve user experience with cache

    CDN acceleration costs money on any CDN, cloudflare is no different, but using all the above is 100% free.

    What is the last stage in the pipeline names “clean-cache” ?

    I used Cloudflare API in order to purge cache, if a deployment passes ok. You can read about that Here And Here if you want to “purge everything”

    Hope this post provided you some useful information Anyway, this is the flow that builds this website you are now reading at.