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 to true, 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 the FROM lines 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 is false. 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 to master, so set this if your repository uses main.

      • 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 the environment key take precedence over variables in the file.

      • manage_volumes: If set to true, Harbormaster stores the named volumes that the app’s Compose file declares in its data and cache directories. See managed volumes. Defaults to false, 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:

        1. compose.yaml

        2. compose.yml

        3. docker-compose.yaml

        4. docker-compose.yml

        Setting compose_config turns 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 as compose.override.yaml by 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 to false, 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.