Hosting a Static Website with Zola, Woodpecker CI and Codeberg Pages

The blog website you're looking at right now exists since about an hour (at the time of me writing this second blog post) and I'm really proud I managed to get it online. In this post I want to describe the process of how I got there. Since I did stuff like this for the first time, I'll probably describe some things incorrectly. Feel free to open an issue to correct me or leave any kind of remark.

Zola

Zola is a static site generator written in the Rust programming language. It takes a few text files (.html files for the site structure, .scss files for the style of the page and .md files for the content) to convert them into a plain website consisting of only .html and .css files in the correct directory structure. If you just want to get up and running quickly, follow along the tutorial at this doc page. In general the documentation is very well-written and there are a lot of things I didn't get into for now. If you're interested, you can also look at the source code for this website here.

Running zola serve allows you to test your webpage locally under an address like 127.0.0.1:1111 (with live reloading as you edit the source files), whereas zola build builds the website and puts it into the public/ directory.

One thing to note is the following: When running zola serve, zola links to your sub-pages relative to the root address 127.0.0.1:1111 (for example as I'm writing this blog post I'm looking at http://127.0.0.1:1111/blog/codeberg-pages/) to preview it. However, when you run zola build, it will replace the http://127.0.0.1:1111 with the base_url you configure in your config.toml file. In my case I have the line

base_url = "https://jdw.codeberg.page"

in my config.toml.

The way to get the zola build command to build the site in a location on some web-server where it is available under the address jdw.codeberg.page is to use Codeberg and Woodpecker.

Codeberg

From the documentation:

Codeberg is not a for-profit corporation but an open community of free software enthusiasts providing a humane, non-commercial and privacy-friendly alternative to commercial services such as GitHub.

Most importantly, this means that you can host your git repositories on Codeberg, file issues, do pull requests, ... much like on GitHub, GitLab, etc. The first step towards getting our website online is to turn it into a git repository and push the repository to Codeberg. The remote repository should be called pages so that it is located at codeberg.org/jdw/pages if we want to use the address jdw.codeberg.page to access the page later. See here and here for more info. Read here how to create the repository.

By the way, the legal structure of Codeberg is that of an e.V.. Since I agree very much with their bylaws and because I think it's important to support free and non-commercial high quality software, I decided to become a member and support the organization financially with 24€ p.a.

Woodpecker

Now we have to use the woodpecker CI tool to run the zola build command from above remotely and put the build output in a location where we can access it under the address jdw.codeberg.page. How to do this is described in the zola documentation.

First we have to get access to a woodpecker instance. One way is to use the woodpecker instance of Codeberg. For this you have to apply here to get access. In my case, access was granted within a few hours. More info about codeberg's woodpecker instance is here. Next you'll have to put this woodpecker config file into the root of your project, add it to git and push to codeberg.

Next, we'll have to create an access token for woodpecker. As remarked in the zola documentation, the access token should allow write access for the repository. Save the token in a secure location for later.

Log into woodpecker, click Add repository to add your pages repository. Click on the settings wheel for the repository, go to Secrets and add your secrets as described in the zola documentation: One with name equal to cbmail and value equal to your codeberg email address and one with name equal to cbtoken and value equal to the access token you generated earlier.

Now, according to the zola documentation, the next time you push a change to a repository, the woodpecker CI tool should run zola build (along with a number of other commands) to build the website and push the files to the pages branch of your repository. In my case I hadn't made such a branch, so I was getting some errors. But as soon as I created a pages branch from main and pushed it to codeberg, everything was working fine.