osixia/docker-openldap-backup: two cron schedules, one volume mount, one caveat

It is a backup layer on top of another image

The first thing the README says is that this image is based on osixia/openldap, and that only the backup extension will be described here. That single sentence tells you what you are adopting. You get the directory, the configuration and the container behaviour of that image, and the repository you are reading adds a scheduler and a place to put archives. It also means the documentation is split, since the Kubernetes examples for this setup live in the other repository rather than here, and anything about the base image itself has to be looked up separately. Treat the two repositories as one project when you read them, and expect to spend the first half of your setup in the one that is not this.

Backups go to /data/backup and need a volume

The container writes backups into a fixed directory inside itself, and the README is emphatic that this should be mapped as a volume so the files survive outside the container. The quick start shows the whole invocation.

      docker run --env LDAP_BACKUP_CONFIG_CRON_EXP="0 5 * * *" \
      --volume /data/openldap/backup:/data/backup \
      --detach osixia/openldap-backup:1.5.0

Three things are visible in those three lines. The image tag is pinned to an explicit version rather than left floating. The volume maps a host directory onto the backup path. And an environment variable overrides one of the defaults, which is the first of the three settings the image exposes. Read without the volume argument, this container would run perfectly and produce archives that vanish when it is removed, which is the failure mode worth checking for first in any deployment of it.

Two cron expressions that default to the same minute

The image exposes exactly three environment variables, and two of them are schedules. One schedules the backup of the OpenLDAP configuration and one schedules the backup of the data, and both default to the same expression, four o'clock every day.

      docker run --env LDAP_BACKUP_CONFIG_CRON_EXP="0 5 * * *" \
      --detach osixia/openldap-backup:1.5.0

The third variable is a time to live in days for the backups, defaulting to fifteen, which is the only retention control on offer. The identical defaults are the detail to notice: on an untouched configuration the configuration backup and the data backup fire in the same minute rather than being spread across the day. Whether that matters depends on the size of your data, but if both jobs are long-running you have just scheduled them to contend, and moving one of them is a one-token edit.

Custom environment files need a numbered subdirectory

This is the caveat the README spends the most words on, and it is a good one. You can supply your own environment settings by mounting a file into the container's environment directory, but you have to put it in a numbered subdirectory rather than at the root of that directory.

	 docker run --volume /data/ldap/environment/my-env.yaml:/container/environment/01-custom/env.yaml \
	--detach osixia/openldap-backup:1.5.0

The naming rule is that the directory should carry a two-digit prefix below ninety-nine, so that your files are processed before the default ones. Mounting straight into the environment directory is what breaks things, because that directory holds the base image's own environment files, which fix the container's locale and initrd settings by name. Overwrite them and you get a container with the wrong character encoding rather than an error message.

Defaults live in a YAML file inside the build context

The default values for all three environment variables are not compiled into a binary; they sit in a YAML file under the image directory, which is also the Docker build context. That matters if you want to change them permanently, and the README gives two ways. The cheap one is to extend the published image with a Dockerfile that adds your own environment directory.

	FROM osixia/openldap-backup:1.5.0
	MAINTAINER Your Name <[email protected]>

	ADD environment /container/environment/01-custom

Note that the example uses the long-deprecated MAINTAINER instruction rather than a LABEL, which is a small sign that the sample has not been revisited in a while. The alternative is to clone the repository, edit the name and version in the Makefile, add your environment files and run make build, which produces an image under whatever name you set.

The release target pushes the image before it tags git

The Makefile is twenty lines and its structure is worth reading before you cut a release, because the order is unusual. The release target depends on five others and runs them in sequence: build, test, then tagging the image as latest, then pushing both the versioned and the latest tags to the registry. Only after all of that does the git tag target create an annotated tag for the version and push it.

release: build test tag-latest push push-latest

git-tag-version: release
	git tag -a v$(VERSION) -m "v$(VERSION)"
	git push origin v$(VERSION)

So the image is public before the source is tagged, and there is no target that commits anything, which means the version bump in the Makefile is a human step. There is also a small dead target in the file: the plain tag target tags the image with its own name and version, which changes nothing. The README's own example still shows version 1.1.9 while the Makefile declares 1.5.0.

Tests are Bats, run through make

The test story is a single line. The image is tested with Bats, described in the README as the Bash Automated Testing System, and the Makefile wires it up by passing the image name and version into the environment and invoking a single test file.

test:
	env NAME=$(NAME) VERSION=$(VERSION) bats test/test.bats

So running the suite locally means installing Bats and running make test, and the test directory holds one bats file. There is a Travis configuration at the repository root, which is how this ran in continuous integration at the time. Given that the whole extension is a scheduler and a copy step, that is a proportionate amount of testing, though it is worth knowing that the suite is one file and not a suite you can extend incrementally.

Log level is a command line argument, not an environment variable

One setting is handled differently from the rest, and the inconsistency is worth knowing before you go looking for an environment variable that does not exist. The container's default log level is info, and the available levels are none, error, warning, info, debug and trace. You set it as an argument after the image name.

	docker run --detach osixia/openldap-backup:1.5.0 --loglevel debug

The full option list is behind a help flag.

	docker run osixia/openldap-backup:1.5.0 --help

So the schedules, the retention window and any custom environment file are environment variables passed before the image name, while the log level is an application argument passed after it. That split is the sort of thing that produces a container that appears to ignore your configuration, and the help flag is the fastest way to confirm which is which.

Editorial conclusion

Use this image if you already run OpenLDAP on the osixia image and want scheduled backups without writing your own container, since the whole extension is three environment variables and a volume. Three things to check before you trust it. Mount a volume at the backup directory or the backups are lost with the container. Change at least one of the two cron expressions, since both default to the same four o'clock schedule. And put custom environment files in a numbered subdirectory rather than at the environment root, where you would overwrite the base image's locale and initrd settings.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes