Installation

There are two ways to run Harbormaster: In a Docker container, and on the host system. The Docker container method is preferable, as it’s much easier to get started with.

Docker container

You can run Harbormaster by using just Docker. You need to follow a few steps to set up your configuration and SSH:

  • Add your harbormaster.yml config (plus associated env/secrets files) to a git repository, and check it out somewhere on the host. That is your “config” directory.

  • If you’re going to be using SSH to pull the above repository, as well as any app repositories (mentioned in the above harbormaster.yml), copy the private SSH key into the config directory, and name it ssh_private_key.

  • Create a directory for Harbormaster to put all the apps’ volumes/data into. That is your Harbormaster working directory.

  • Run the Harbormaster image:

docker run -d \
    --restart unless-stopped \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v <the path to your config directory>:/config \
    -v <the path to your Harbormaster working directory>:/main \
    stavros/harbormaster

Harbormaster will now run every five minutes, pull your config repository (from whatever remote the repo has as its origin), and run the apps in the config.

If you want to run it immediately at some point, you can use the following command:

$ docker exec -i -t <container id> /usr/bin/run-harbormaster

Alternatively you can use stavros/harbormaster:webhook, which is the same image plus webhook, so you can trigger a run over HTTP (for example from a GitHub, Gitea or Forgejo webhook). To use it, you must publish webhook’s port and set a secret:

docker run -d \
    --restart unless-stopped \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v <the path to your config directory>:/config \
    -v <the path to your Harbormaster working directory>:/main \
    -p 9000:9000 \
    -e HARBORMASTER_WEBHOOK_SECRET=<a secret you generate> \
    stavros/harbormaster:webhook

If HARBORMASTER_WEBHOOK_SECRET is unset or empty, the image deliberately refuses to start webhook (it logs why and just runs its scheduled updates), so webhook-triggered runs only work once you set a secret. The secret authenticates requests in two ways, both sent to http://<host>:9000/hooks/run:

  • As a webhook from GitHub, Gitea or Forgejo: point the provider’s webhook at that URL and put the HARBORMASTER_WEBHOOK_SECRET value in the provider’s “Secret” field. Harbormaster verifies the X-Hub-Signature-256 header those providers send.

  • By hand or from a script, with an X-Harbormaster-Token header:

curl -X POST -H "X-Harbormaster-Token: <your secret>" http://<host>:9000/hooks/run

The image comes with the above hook at /hooks.json, reading the secret from the environment. If you need anything different, mount your own JSON file there with the proper rules for verifying the source; a plain-JSON file works as-is.

System installation

To install it on your system, you can use pipx (recommended):

$ pipx install docker-harbormaster

Or pip (less recommended):

$ pip install docker-harbormaster

You also need to make sure you have git installed on your system.