Nikola Gitlab Pages No-Brainer IndieWeb Guide

1. Pre-requisites and disclaimer

We assume you’ve got basic knowledge of using git and Python infrastructure.

We’ll use git to keep the content of your site. We’ll use Python to run Nikola static site generator.

In order not to write everywhere “for example”, we’ll mark variable strings with double curly quotes: “name it {{some_name}}”. Feel free to variate any step if you’re aware what you’re doing.

Of course, there are plenty of alternatives for every single choice on this guide. I’ll add them later as spoilers, in order not to break the flow.

2. Buy a domain name

  1. Search for a great domain name at namecheap.

  2. Try to choose a TLD with “WhoisGuard”. That’ll close your private data from 3rd parties.

  3. Notice the renewal price. It comes on the second and following years and could be quite high.

  4. In 90% of possible cases you should be in range of 10-20$ per year. If not, check it twice.

  5. During checkout turn on “auto-renew” for “WhoisGuard”, it’s free. Turn on “auto-renew” for domain registration if you’re afraid to forget about it.

Don’t close the browser tab: we’ll return here right after creating and tuning the Pages repository.

3. Create a GitLab account and site repository there

If you’ve got a GitLab account with the SSH keys set up, start from step 8.

  1. Register to GitLab or sign in with a third-party.

  2. Set up your SSH public key.

  3. Create new project “{{username}}.gitlab.io” there. Choose private for visibility level. The username part here must be the username of your GitLab account. Yes, it’s the part after gitlab.com/ at your profile address https://gitlab.com/{{username}}.

  4. Visit the Pages settings of the new project at https://gitlab.com/{{username}}/{{username}}.gitlab.io/pages. Push the “New domain” button. Enter “https://{{your-domain.com}}” for “Domain” and turn on the “Certificate” checkbox.

  5. After creating the new domain copy the text similar to _gitlab-pages-verification-code.{{your-domain.com}} TXT gitlab-pages-verification-code={{a0bc186be3df54c6e7ad0890cb50a8b0}} to your favourite notepad application.

4. Set the domain up

We have to do this techy stuff first, since it’ll take some time to wait for the effect (up to 24-48 hours).

  1. On namecheap dashboard you should see your single domain in a list. Push the “Manage” button.

  2. On the “Domain” tab scroll down to the “Redirect email” section. With alias “hi” mail sent to “hi@your-domain.com” will be sent to the forward address you choose.

  3. On the tab “Advanced DNS” remove all the records in the “Host records” section, if any.

    Create DNS record that links your domain name to the Pages IP address:

    • Type: A Record

    • Host: @

    • Value: 35.185.44.232

    Add another DNS record to make GitLab verify your ownership for the domain; use your favourite notepad application with the text copied:

    • Type: TXT Record

    • Host: _gitlab-pages-verification-code.{{your-domain.com}}

    • Value: gitlab-pages-verification-code={{a0bc186be3df54c6e7ad0890cb50a8b0}}

Congratulations! You’re all up with the domain. Let’s move to creating some sample content.

5. Clone the project repository and push the sample Nikola site there

  1. Clone the project repository to any suitable place locally.

    cd {{~/projects_folder}}
    git clone git@gitlab.com:{{username}}/{{username}}.gitlab.io.git
    cd {{username}}.gitlab.io
    
  2. Optionally set python version for the repo: pyenv local 3.8.2

  3. Install Nikola into a separate virtual env and activate it.

  4. Bootstrap its default site: nikola init --demo {{proj_name}}

  5. Change the output folder in the {{proj_name/conf.py}}:

    OUTPUT_FOLDER = '../public'
    

    This is a requirement of GitLab pages: the static site must be in the public directory of the project root.

  6. Build the demo site and run it locally:

    cd {{proj_name}}
    nikola auto
    

    Check the demo-site is working on localhost:8000.

  7. Add the .gitignore file to the project root containing:

    cache
    /public
    .doit.db
    
  8. Add the .gitlab-ci.yml file to the project root with this content:

    image: registry.gitlab.com/paddy-hack/nikola
    
    test:
      script:
      - nikola build
      except:
      - master
    
    pages:
      script:
      - cd {{proj_name}}
      - nikola build
      artifacts:
        paths:
        - public
      only:
      - master
    
  9. Add all the files in the repo (except ignored) to new commit and push.

  10. After the push pipeline has finished check your site to be deployed to https://{{username}}.gitlab.io.

6. Final touches

  1. Check that demo-site is available on the https://{{your-domain.com}}. If not, recheck after 24-48 hours. If still not, try to investigate or write me on the IndieWeb slack chat.

  2. Create new post with Nikola and run nikola auto for your comfort.

  3. If stuck with any part of Nikola look through comprehensive Nikola handbook.

  4. And the last thing: enjoy your brand new site!