# Setting up Pelican to Automatically Deploy to GitLab Pages

Source: https://sumnerevans.com/posts/technology/pelican-on-gitlab-pages/
Published: 2019-08-27
Programming, 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 made a few major shifts in my personal
> website infrastructure. I migrated from GitHub to GitLab and subsequently from
> GitLab to sourcehut. Then I migrated from Pelican to [Hugo](https://gohugo.io)
> and hosted my website on a Linode VPS for a while before migrating back to
> GitHub and GitHub Pages.

I posted last year about my switch from WordPress to a statically generated site
generated by Pelican by GitHub Pages in a
[blog post](https://sumnerevans.com/posts/technology/pelican-on-github-pages/). 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.

> [!NOTE] 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](http://docs.getpelican.com/en/stable/quickstart.html)
>   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.

1. Make sure that all of your Pelican source code is committed to a branch in
   your repository.

2. 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](https://gitlab.com/sumner/sumnerevans.com/blob/master/Makefile).

   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.

3. 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:

   ```plain
   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:

```yaml
# 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:

1. Edit your domain's DNS CNAME record to point to GitLab (GitLab should give
   you the exact CNAME value that you need to use).
2. 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!