Soupault generates static sites, so you can host generated pages anywhere. The simplest option is to build your site on your own computer and copy generated pages to the server.
It may not be the easiest option though: you cannot edit your site from a device that doesn’t have a soupault build setup, and you need to remember to rebuild and update the site whenever you make an edit.
The good news is that soupault is easy to integrate into an automated CI setup. Since it comes as a statically linked executable, you only need to download and unpack the archive.
→ Getting soupault
Since most of the hosting and CI services offer build hosts with preinstalled soupault yet, you’ll need to download it as a part of your website build process.
Since the Linux version of soupault is a statically linked executable, you can run it on any Linux-based build host without any trouble.
The primary location for soupault downloads is files.baturin.org/software/soupault/.
However, for a CI process, you may rather want to use a CDN’d link. For this reason I mirror releases to GitHub. Examples below use GitHub links.
Netlify is a popular static site hosting platform that has a built-in continuous integration service.
One disadvantage is that as of early 2023, Netlify only provides a single Ubuntu LTS build image. Worse yet, they do not give you root permissions in the container, so you cannot install packages from APT repositories. So, if you want to use external programs in your workflow, Netlify’s built-in CI isn’t for you, unless all programs you need are already in their container image or they are easy to get as downloadable executables.
Warning: if you are using external CI for your Netlify sites, make sure to go to “Site settings”, “Build & deploy”, and tick the “Stop builds” option there. Otherwise Netlify will try ‘building’ your site with its built-in process even if you don’t have
netlify.toml in your repository, which will produce an empty website. Thus, if you don’t disable those builds by hand, then a) your website will be emptied when a deploy is triggered and will stay empty until the external CI job completes b) if the external CI job fails, the website will remain empty forever. Make sure to “Stop builds” to prevent that.
If everything you need can be installed without root permissions, then their built-in CI service can be very nice to use though. On the plus side, Netlify allows rather free-form build scripts and doesn’t make you write fragile YAML files.
First you need a build script.
#!/bin/sh SOUPAULT_VERSION="4.7.0" wget https://github.com/PataphysicalSociety/soupault/releases/download/$SOUPAULT_VERSION/soupault-$SOUPAULT_VERSION-linux-x86_64.tar.gz if [ $? != 0 ]; then echo "Error: failed to download soupault." exit 1 fi tar xvf soupault-$SOUPAULT_VERSION-linux-x86_64.tar.gz ./soupault-$SOUPAULT_VERSION-linux-x86_64/soupault
Then you need to tell the builder what script to run and which directory to publish. This is specified in the
[build] publish = "build/" command = "./netlify.sh"
→ GitHub Actions
GitHub Actions is Microsoft GitHub’s built-in CI service.
- For GitHub users: tight integration with the rest of GitHub.
- Good selection of build images, newer GNU/Linux distro versions.
The build part in
.github/workflows/main.yml boils down to this:
jobs: build: # The type of runner that the job will run on runs-on: ubuntu-latest # Steps represent a sequence of tasks that will be executed as part of the job steps: # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - uses: actions/checkout@v2 - name: Install soupault env: SOUPAULT_VERSION: 4.7.0 run: | echo Downloading and unpacking soupault wget https://github.com/PataphysicalSociety/soupault/releases/download/$SOUPAULT_VERSION/soupault-$SOUPAULT_VERSION-linux-x86_64.tar.gz tar xvf soupault-$SOUPAULT_VERSION-linux-x86_64.tar.gz sudo mv -v ./soupault-$SOUPAULT_VERSION-linux-x86_64/soupault /usr/bin/ - name: Build the site run: | soupault # Your deployment steps here
→ Sourcehut + NixOS
In your project directory, create a build configuration
$ touch .build.yml
The simplest configuration
image: nixos/unstable # at the time of writing, soupault only available in unstable packages: - nixos.soupault # … any additional dependencies (e.g. preprocessors) # - nixos.asciidoctor environment: repo_name: "$YOUR_SOURCEHUT_REPOSITORY_NAME" tasks: - build: | cd "$repo_name" soupault # add other tasks such as deployment via `curl`