Tome of Finite Knowledge

Woodpecker Pipelines

2 min read

Note: I’m writing this as I’m getting my first Woodpecker pipeline to run, so please excuse the somewhat confused format!

Potentially outdated

While the information on this page isn’t wrong, if you’ve landed here because it references sphinx publishing, I’ve switched to an Obsidian-based approach instead.

Goals

Here’s what I want to happen:

  1. I make some changes, commit, and push them to Gitea
  2. Woodpecker is triggered to build my docs (either via the push trigger or manual go-click-button)
    1. Woodpecker downloads sphinxdoc/sphinx-latexpdf docker image
    2. Woodpecker starts up the container
    3. The container runs the build command(s, one for each format)
    4. The files are left behind in a persistent volume
    5. Woodpecker tears down the build container
  3. The web server container (haven’t picked one yet) serves the files

Setup

Starting off with a basic CI file:

when:
  - event: push
    branch: master
  - event: manual
 
steps:
  - name: build
    image: sphinxdoc/sphinx-latexpdf
    volumes:
      - /opt/docker/tome-of-finite-knowledge/build:/docs
    commands:
      - sphinx-build -M html source build

At this point, trying to run the pipeline Woodpecker throws an error: Insufficient trust level to use volumes. You must mark each project as “trusted” in order to create networks, volumes, and have other security priviliges. Only Woodpecker server admins can do this! As an admin, go to the repository, click Settings, then set the appropriate options under the Trusted section.

See also

Woodpecker docs on trusted projects: https://woodpecker-ci.org/docs/usage/project-settings#trusted

It builds!

… but /opt/docker/tome-of-finite-knowledge is totally empty.

Seems I just got the volume path wrong. Setting that volume to

volumes:
  - /opt/docker/tome-of-finite-knowledge/build:/woodpecker/src/gitea.my.domain/mishaturnbull/tome-of-finite-knowledge/build

gets me doctrees and html in the folder on disk! Success!

Hosting the site

Having some files on a random mini-pc doesn’t do me any good. First try: httpd:

tome-of-finite-knowledge:
  image: httpd:latest
  container_name: tofk
  restart: unless-stopped
  ports:
    - 8000:80
  volumes:
    - /opt/docker/tome-of-finite-knowledge/build/html:/usr/local/apache2/htdocs

and… it works!

Triggers

After a few branches, I noticed the “build on push” feature wasn’t building when I pushed a commit. Digging around a bit in the Gitea settings eventually got me this error message:

webhook can only call allowed HTTP servers (check your webhook.ALLOWED_HOST_LIST setting)

so, setting that in the Gitea settings (I manage them all through compose environment variables):

gitea:
  ...
  environment:
    ...
    GITEA__webhook__ALLOWED_HOST_LIST: woodpecker.my.domain

it works as intended.

Graph View

Backlinks