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 itssh_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 ships with
webhook to trigger updates. The image comes with
an example configuration but you should mount a custom one to /hooks.json
with proper
rules for verifying
the source.
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.
You can also download a standalone executable for Linux from the pipelines page.
Recommended deployment for a system installation
The recommended way to run Harbormaster is on a timer. You can use systemd, with two files. Put the Harbormaster configuration YAML in a repository, and clone it somewhere. Then, use the two files to run Harbormaster in that repository.
/etc/systemd/system/harbormaster.service:
[Unit]
Description=Run the Harbormaster updater
Wants=harbormaster.timer
[Service]
ExecStart=/usr/local/bin/harbormaster run
ExecStartPre=/usr/bin/git pull
WorkingDirectory=<the repository directory>
[Install]
WantedBy=multi-user.target
/etc/systemd/system/harbormaster.timer:
[Unit]
Description=Run Harbormaster every few minutes.
Requires=harbormaster.service
[Timer]
Unit=harbormaster.service
OnUnitInactiveSec=5m
[Install]
WantedBy=timers.target
Then, run:
sudo systemctl daemon-reload
sudo systemctl enable harbormaster
# To run Harbormaster immediately:
sudo service harbormaster start
# To check the Harbormaster run logs:
sudo journalctl -fu harbormaster
This will run Harbormaster every five minutes, pulling your configuration repository before the run.
Now that Harbormaster is installed, you can learn how to use it.