Configuring Harbormaster
Harbormaster uses a single YAML configuration file to manage the deployment of Compose apps. Below is an example of a typical configuration file:
config:
prune: true
apps:
myapp:
url: https://github.com/someuser/somerepo.git
branch: main
manage_volumes: true
environment:
FOO: bar
MYVAR: 1
environment_file: "somefile.txt"
otherapp:
url: https://gitlab.com/otheruser/otherrepo.git
compose_config:
- docker-compose.yml
- docker-compose.harbormaster.yml
environment_file: "somefile.yml"
oldapp:
enabled: false
url: https://gitlab.com/otheruser/otherrepo.git
Configuration directives
config: Top-level configuration options.prune: If set totrue, Harbormaster deletes every Docker image that no enabled app uses after each run, to save space on the host. An enabled app uses the images named in its Compose file and, best effort, the base images named in theFROMlines of the Dockerfiles it builds. Images of disabled or removed apps, old versions, and dangling images are deleted. Images that any container uses, running or stopped, are kept, and containers, networks, the build cache and volumes are never touched. If the image list of any enabled app cannot be read, the prune is skipped for that run. The default isfalse. Turning it on is recommended when the host only runs Harbormaster. Be careful on a shared host, as it will also delete Docker images on your system that are unrelated to Harbormaster.
apps: A list of applications to deploy.myapp: The name of the application. It can be anything you want.url: The git repository URL to clone.branch: The branch to deploy. Defaults tomaster, so set this if your repository usesmain.environment: The environment variables to run Compose with.environment_file: A file to load environment variables from. The file must consist of lines in the form of key=value. The filename is relative to the Harbormaster config file (this file). The file can also be a YAML file, with a .yml or .yaml extension, containing a single YAML collection of string values. Variables in theenvironmentkey take precedence over variables in the file.manage_volumes: If set totrue, Harbormaster stores the named volumes that the app’s Compose file declares in its data and cache directories. See managed volumes. Defaults tofalse, but enabling it is strongly recommended, and it is the way new apps should mount their data.
otherapp: Another application to deploy.compose_config: The Compose config filename, or a list of them, if you want to use Harbormaster-specific overrides or a name that Harbormaster does not look for on its own.If you leave this out, Harbormaster looks for the Compose file in the repository itself, checking the same names as Compose, in the same order, and using the first one it finds:
compose.yamlcompose.ymldocker-compose.yamldocker-compose.yml
Setting
compose_configturns this off, and the names you give are used as they are. Note that Harbormaster only looks for the four names above, and never adds an override file such ascompose.override.yamlby itself, so if your app needs more than one file, you must list them all here.environment_file: A YAML environment file.
oldapp: An old application that shouldn’t be run.enabled: If set tofalse, the app will not be run.url: The git repository URL to clone. Two apps can use the same repo, in case you want to have multiple apps in the same repo (with different Compose filenames, or on different branches).
To execute Harbormaster, run harbormaster run in the same directory as the
configuration file. Harbormaster will parse the file, automatically download the
repositories mentioned in it and keep them up to date.
Note: Ensure that the Compose config in each of the repos does not use the
container_name directive, otherwise Harbormaster might not always be able to find your
apps and restart them when necessary.