Setting up Pelican to Automatically Deploy to GitLab Pages

Posted on 2019-08-27 in Technology • 906 words • 5 minute read
Tags: Pelican, GitLab, GitLab CI/CD, GitLab Pages

Warning

This article is out of date, and may contain outdated information.

Since writing this article, I have migrated from Pelican to Hugo. I have also migrated away from GitLab to sourcehut and I'm deploying my site to a Linode VPS.

I posted last year about my switch from WordPress to a statically generated site generated by Pelican by GitHub Pages in a blog post. Since then, my hosting situation has changed a couple of times. I first migrated to deploy straight to a DigitalOcean Droplet from Travis CI. Then, I migrated to GitLab and used GitLab CI/CD to do the same thing. Now that GitLab Pages has support for automatically handling the Let's Encrypt SSL Certificate on custom domains, I've moved to GitLab Pages for hosting as well.

In summary, I am hosting my site publicly on GitLab Pages here: https://sumnerevans.com. Unlike my previous setup, the master branch is the branch from which everything is deployed. When a new commit is added to master, I use GitLab CI/CD to deploy to GitLab Pages automatically. Currently, it takes about 2-3 minutes for it to deploy after I commit a change.

In this article, I'm going to walk you through how to set up the deployment pipeline to get your site deploying on GitLab Pages.

Prerequisites

For this article, I assume that you...

Already have basic competency in Git and GitLab (although I don't assume knowledge of GitLab CI/CD).
I assume that you already have a Pelican site setup. If you don't, the Pelican Documentation is really good. The pelican-quickstart command works great, and will help you easily get started with your site.

Setting up Pelican

First, we need to make sure that Pelican is configured to output to the correct directory so that GitLab Pages can find the site files.

Make sure that all of your Pelican source code is committed to a branch in your repository.
Make sure that Pelican is set up with a Makefile which publishes the site to <repo_root>/public. The pelican-quickstart script can automatically generate this for you. If not you can look at the one for this site and adapt to your needs here.
If using the pelican-quickstart Makefile, ensure sure that the OUTPUTDIR is set to $(BASEDIR)/public as that is required for GitLab Pages to recognize your site's files.
If you have not already created a requirements.txt file, do so now in the root of your repository. It needs at least the following content:
```
pelican
Markdown
beautifulsoup4
```
Add any other dependencies of your site to this file. (My site depends on typogrify as well, so that is also in the requirements.txt file.)

Set up GitLab CI/CD

Now we need to configure GitLab CI/CD to automatically build the site. To do that, add a .gitlab-ci.yml file with the following contents:

# Build and deploy the pelican site.
pages:
  image: python:3.6-alpine
  stage: deploy
  only:
    - master
  before_script:
    - apk update && apk upgrade && apk add git make
    - pip install --upgrade pip
    - pip install -r requirements.txt
  script:
    - make publish
  artifacts:
    paths:
      - public

Note

The above file is assuming that you are using a pelican-quickstart Makefile, and that you only want to deploy the master branch. Modify as necessary if you are using a different Makefile or branch.

Also, if you have any other dependencies or custom build steps, add them to before_script or script.

Now, commit and push that file to GitLab, and let the magic occur. You can view the status of your build by going to the "CI / CD" tab of your repo. You can also access the settings for GitLab Pages in "Settings -> Pages". There you can add a new domain to allow it to use a custom domain (as I do), and otherwise manage your site.

Optional: Set up a Custom Domain

By default, your website will be hosted at a site similar to this: https://sumner.gitlab.io/sumnerevans.com/. That's the default site for GitLab Pages. GitLab allows you to use a custom domain, which is what I'm doing (and which is why you are probably seeing this article on https://sumnerevans.com). I also let GitLab handle the Let's Encrypt certificate so that my site is served with HTTPS.

To set this up, go to the Settings of your repository, and click on "Pages" in the sidebar. From there, click on "New Domain" and enter in your domain. Then, toggle the switch which says "Automatic certificate management using Let's Encrypt". Then, you need to follow the instructions on the next page. There are two steps that you have to do:

Edit your domain's DNS CNAME record to point to GitLab (GitLab should give you the exact CNAME value that you need to use).
Add a DNS TXT record to verify that you are, in fact, the owner of the domain.

If you don't know how to do that, then I recommend that you look up the documentation for your domain name registrar.

Once you have done all of this and the DNS records have propagated (you may have to click the "Refresh" button to make GitLab check the verification status), it will automatically acquire a Let's Encrypt certificate for your domain.

Conclusion

That's it! Your site should not be available at the URL that the "Settings -> Pages" has listed. Whenever you commit new changes to master, it will automatically rebuild the site, and deploy it to GitLab Pages. Go ahead; try it out for yourself!