statichost.eu logo
Documentation

Scroll to menu

Build configuration

Builds are configured using a statichost.yml file in the root of your repository. In this file, you need to specify the Docker image and command to use and the output (public) directory for the generated site. The needed configuration options can be seen in this sample configuration file for a Jekyll site are:

statichost.yml

# Docker image to use for building
image: jekyll/jekyll:3.8
# Build command
command: jekyll build
# Public directory
public: _site

The example above will in practice run a Docker container similary to: docker run --entrypoint /bin/sh jekyll/jekyll:3.8 -c 'jekyll build' with the repository root as the working directory. After the build is done, the contents of the _site directory are published.

Build image

On statichost.eu, you can use any Docker image to build your site. This gives you complete freedom to choose your build environment. For instance, a Node- based project (Next.js, Gatstby, etc.) might use the node:18.16.0 image while a Hugo-based project might use klakegg/hugo:0.111.3-ext-ubuntu-ci. If you have trouble finding a suitable image for your site, contact us, and we will help you!

While the examples above all use Docker Hub, any (public) container registry and (public) image will work. E.g. GitHub Container registry images will work great.

We highly recommend you specify the image with a version-based tag (e.g. :18.16.0 from the Node example above). This way, you will get the correct software versions for your build.

The image option is optional. If you do not specify an image to run, no build container will be run. Instead, the contents of the public directory will be published as-is without any build step.

Build command

The build command is what will be executed inside your container when running the build. The command will be executed using /bin/sh, which means you can use shell functions such as && in order to chain multiple commands. For instance a Node-based site might use npm install && npm build as the build command. *

The repository root is mounted inside the container under /repo, which is used as the working directory for the build command.

The command option is optional. If you do not specify a command, the container will be run using the default entrypoint (and the default command, if any). For instance this site uses the klakegg/hugo image, which has hugo as the default entrypoint. So for this site no build command is set, instead relying on the default behavior of the image.

You can see the Docker CLI command used to run your build in the on the build details page. (We don’t use the Docker CLI, but this command should be fully equivalent to what is run in our environment.)

*) This is technically implemented by setting /bin/sh as the entrypoint for the Docker image and running the command with the -c argument for sh. E.g. docker run --entrypoint /bin/sh node:18.16.0 -c 'npm install && npm build'

Output directory

The public option specifies which directory to deploy. It is the directory that contains the generated static content for your site. This is relative to the repository root, and might be e.g. public or dist. Our build servers run Linux, so please use a forward slash (/) if your output directory is nested inside another directory.

The image and command options above are optional. If you do not specify an image to run, the contents of the public directory will be published as-is without any build step. The most minimal configuration that just publishes the entire contents of the repo is thus:

statichost.yml

# Public directory is a dot, i.e. repository root
public: .

Environment variables

Setting environment variables, such as authentication tokens needed for your CMS, inside the build environment (/container) is supported. If you need environment variables as part of your build, please contact us, and we’ll sort it out.

Automatic SSG detection

We will try to determine the static site generator you use automatically and build your site appropriately. However, this might not always succeed - or you might want more control over how your site is built. In this case, create a statichost.yml configuration file in the root of your repository. The available configuration options are:

Currently, automatic SSG detection works for the following static site generators: