Docker Labels

Docker Labels allow us to apply settings to Nautical on a per-container basis. Instead of applying environment variables, we can apply the label to the each container separately.

How to add labels¶

Here are a few examples of how to add labels to a Docker container. Remember, these labels can be added to any container (other than Nautical itself).

Docker Compose Example 1Docker Compose Example 2Docker Run Example 1Docker Run Example 2

version: '3'
services:
  # Service config ...
  labels:
    - "nautical-backup.enable=true"
    - "nautical-backup.stop-before-backup=true"
    - "nautical-backup.rsync-custom-args= " # Disable custom rsync args

version: '3'
services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80/tcp"
    volumes:
      - './etc-pihole:/etc/pihole'
      - './etc-dnsmasq.d:/etc/dnsmasq.d'
    labels:
      - "nautical-backup.enable=true"
      - "nautical-backup.stop-before-backup=true"

docker run --name example-image \
-l nautical-backup.enable=true \
-l nautical-backup.stop-before-backup=true \
my-image:latest

docker run -d \
  --name pihole \
  -p 53:53/tcp -p 53:53/udp \
  -p 80:80 \
  -e TZ="America/Chicago" \
  -v "${PIHOLE_BASE}/etc-pihole:/etc/pihole" \
  -v "${PIHOLE_BASE}/etc-dnsmasq.d:/etc/dnsmasq.d" \
  -l nautical-backup.enable=true \
  -l nautical-backup.stop-before-backup=true \
  pihole/pihole:latest

Label vs Environment Variable Priority¶

If a container has an Environment Variable applied as well as a conflicting Label, then:

The container Label takes priority over the global Nautical environment variable.

Enable or Disable Nautical¶

This Docker label can be used to achieve 2 things:

Opt a container OUT of backup
Opt a container IN to a backup (with the Nautical Require Label environment variable set to true)

Default If Missing: true (all containers will be enabled, unless Require Label is set to true).

nautical-backup.enable=true

Example 1 (Opt out)Example 2 (Opt in)

With the Require Label environment variable not set or set to false.

services: # Example Service #1 config ...
  labels:
    - "nautical-backup.enable=false"

services: # Example Service #2 config ...
  labels:
    - "nautical-backup.enable=true"

services: # Example Service #3 config ...
  labels: 
    # No labels

The results of this configuration would be:

Service 1 - Skipped since nautical-backup.enable was set to false
Service 2 - Backed up since the label nautical-backup.enable=true was present
Service 3 - Backed up since no nautical-backup.enable=false label was found
- The Require Label environment variable was either not set or set to false for this example

With the Require Label environment variable set to true

services: # Example Service #1 config ...
  labels:
    - "nautical-backup.enable=true"

services: # Example Service #2 config ...
  labels:
    - "nautical-backup.enable=false"

services: # Example Service #3 config ...
  labels: 
    # No labels

The results of this configuration would be:

Service 1 - Backed up since the label nautical-backup.enable=true was present
Service 2 - Skipped since nautical-backup.enable was set to false
Service 3 - Skipped since no nautical-backup.enable=true label was found

🔄 nautical-backup.enable=false is the same action as the Skip Containers variable, but applied only to this container.

Stop Container Before Backup¶

With this label set to false, the container will not be stopped before performing a backup.

Default If Missing: true (container will be stopped before backup).

nautical-backup.stop-before-backup=false

Not stopping containers can produce corrupt backups.

Containers with databases--particularly SQL--need to be shutdown before backup.

Only do this on containers you know for certain do not need to be shutdown before backup.

🔄 This is a similar action to the Skip Stopping Containers variable, but applied only to this container.

Groups¶

Use this label to have multiple containers stopped, backed up, and restarted at the same time.

This is useful for services that require multiple containers.

Default If Missing: none (no groups, will be handed independently)

Format: <string> (comma separated for multiple items)

nautical-backup.group=group_name

Example 1Example 2

In this example, we define two groups: paperless and authentic. The redis container is shared between two groups and will be backed up both times.

paperless-ngx:
  labels:
    - "nautical-backup.group=paperless"

redis:
  labels:
    - "nautical-backup.group=paperless,authentic"

authentic-worker:
  labels:
    - "nautical-backup.group=authentic"

In this example, the authentic folder is defined for all the containers used by Authentic.

They do not need to be part of the same docker-compose file.

services:
  authentik-worker-1:
    labels:
      - "nautical-backup.group=authentic"
  authentik-postgresql-1:
    labels:
      - "nautical-backup.group=authentic"
  authentik-redis-1:
    labels:
      - "nautical-backup.group=authentic"

Group Priority (Order)¶

When using the Groups feature, the Priority will allow you to control the order in which containers are started/stopped.

Containers within a group are backed up with the highest priority first, in descending order.

Default If Missing: 100

Format: <integer>

nautical-backup.group.<group_name>.priority=<integer>

Example 1Example 2

The backup order for the group paperless is: paperless-ngx (105) → redis (90)
The backup order for the group authentic is: authentic-worker (100/default) → redis (85)

paperless-ngx:
  labels:
    - "nautical-backup.group=paperless"
    - "nautical-backup.group.paperless.priority=105"

redis:
  labels:
    - "nautical-backup.group=paperless,authentic"
    - "nautical-backup.group.paperless.priority=90"
    - "nautical-backup.group.authentic.priority=85"

authentic-worker:
  labels:
    - "nautical-backup.group=authentic"

The backup order for the group authentic is: worker (110) → redis (105) → postgresql (100)

services:
  authentik-worker-1:
    labels:
      - "nautical-backup.group=authentic"
      - "nautical-backup.group.authentic.priority=110"
  authentik-postgresql-1:
    labels:
      - "nautical-backup.group=authentic"
      - "nautical-backup.group.authentic.priority=100"
  authentik-redis-1:
    labels:
      - "nautical-backup.group=authentic"
      - "nautical-backup.group.authentic.priority=105"

Require Source Folder for Backup¶

Use this label to tell Nautical to process (start/stop) this container even if it cannot find a matching source directory.

Default If Missing: true (container will be skipped if no matching source folder is found)

nautical-backup.source-dir-required=false

Example

Here we have an example Immich deployment. Notice the immich-server does not have any mounted directories, but we still want to stop/start it along with it's other services. This is especially helpful when combined with the Groups feature.

immich-server:
  container_name: immich_server
  volumes:
    # No volumes to backup
  labels:
    - "nautical-backup.group=immich"
    - "nautical-backup.source-dir-required=false"

immich-redis:
  container_name: immich_redis
  volumes:
    - ${APPDATADIR}/immich/redis:/data
  labels:
    - "nautical-backup.group=immich"
    - "nautical-backup.override-source-dir=immich/redis"

immich-database:
  container_name: immich_postgres
  volumes:
    - ${APPDATADIR}/immich/database:/var/lib/postgresql/data
  labels:
    - "nautical-backup.group=immich"
    - "nautical-backup.override-source-dir=immich/database"

Additional Folders¶

Use this label to backup more folders associated with the container.

The additional folders must either exist or be mounted into the app/source folder within Nautical.

Default If Missing: none (no additional folders)

Format: <folder_name> (comma separated for multiple items)

nautical-backup.additional-folders=folder1,folder_name2

When to backup additional folders?¶

Use this setting to decide if when the additional folders are backed up.

Default: during

Options: during, before, after

nautical-backup.additional-folders.when=after

During (Default) - Backup the additional folders while the parent container is stopped. (This is the safest option).
Before - Backup the additional folders before the parent container is stopped.
After - Backup the additional folders after the parent container is restarted.

Example 1Example 2

In this example, the service-additional folder already exists withing the source directory, so no additional mount point is needed.

services:
  # Service config ...
  labels:
    - "nautical-backup.additional-folders=service-additional"

services:
  nautical-backup:
    image: minituff/nautical-backup:2.6
    container_name: nautical-backup
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /config:/config
      - /source:/app/source

In this example, the service-additional folder is mounted from a different directory on the host machine.

Also, the additional folders are backed up after the service is restarted.

services:
  # Service config ...
  labels:
    - "nautical-backup.additional-folders=service-additional"
    - "nautical-backup.additional-folders.when=after"

services:
  nautical-backup:
    image: minituff/nautical-backup:2.6
    container_name: nautical-backup
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /config:/config
      - /source:/app/source
      - /mnt/service-additional:/app/source/service-additional #(1)!

Mount service-additional inside the /app/source directory in the container

If the same folder is called out by the Additional Folders variable and a service label--it will be backed up twice.

🔄 This is the same action as the Additional Folders variable, but applied only to this container.

Override Source Directory Name¶

Changes the source directory name that Nautical will look for.

By default, Nautical will look for the source directory that is the same name as the container name.

Default If Missing: empty (use container name)

Example 1Example 2Example 3

nautical-backup.override-source-dir=new_folder_name

To backup the container Pi.Alert, the source directory name must be named Pi.Alert, but we can use the override to allow a backup of the folder named pialert.

nautical-backup.override-source-dir=pialert

We can use a nested folder by simply appending it to the source path

nautical-backup.override-source-dir=subfolder/example1

The example above would yield the following results:

Container Name	Old Source Directory	New Source Directory
example1	`src/example1`	`src/subfolder/example1`

Another nested folder example can be found here

🔄 This is the same action as the Override Source Directory variable, but applied only to this container.

Override Destination Directory Name¶

Changes the destination/output directory name that Nautical will create during backups.

By default, Nautical will create destination directory that is the same name as the container name.

Default If Missing: empty (use container name)

nautical-backup.override-destination-dir=new_folder_name

🔄 This is the same action as the Override Destination Directory variable, but applied only to this container.

Mirror Source Directory Name to Destination¶

Mirror the source folder name to the destination folder name. By default (without any overrides), this means both the source and destination folder names are the same as the container name.

When using a source directory override, then the nautical-backup.keep_src_dir_name=true setting (which is the default) will mean the destination directory will be the same as the source directory, without using a destination directory overrides.

If a destination directory override is applied for a container, then the override will be used instead of mirroring the source name, regardless of the KEEP_SRC_DIR_NAME setting.

Default If Missing: true

nautical-backup.keep_src_dir_name=false

🔄 This is the same action as the Mirror Source Directory Name to Destination variable, but applied only to this container.

Execute Commands¶

Execute a command before, after or during backing up the container. This can be used to alert the service before shutdown and/or ensure the service came online correctly.

Default: empty (nothing will be done)

FORMAT: The entirety of a command

nautical-backup.exec.before=/config/prepare-for-backup.sh
nautical-backup.exec.after=curl -X POST 'http://192.168.1.21.com/do-something'
nautical-backup.exec.during=curl -X PATCH 'bing.com'

Remeber, these commands are exectuted by the Nautical-Backup container, not the child container.

If you need to exectute commands inside the continer being backed up, see lifecycle hooks.

There are 3 moments when you can run a command (You can use more than 1):

Before - Run the command before the parent container is stopped.
After - Run the command after the parent container is restarted.
During - Run the command while the parent container is stopped (Before it is restarted).

Test your exec

Before setting the variable/label, it is a good idea to ensure it works first. Here is an example.

Ensure Nautical is running first, then run:

docker exec -it nautical-backup \
  curl -X GET 'google.com'

Note: You can only have 1 before and 1 after Curl Request. This applies to Nautical itself, not to each container.

Available Enviornment Variables

Method	Description
`NB_EXEC_CONTAINER_NAME`	The container name*
`NB_EXEC_CONTAINER_ID`	The contianer ID*
`NB_EXEC_BEFORE_DURING_OR_AFTER`	When is this command being. Options
`NB_EXEC_COMMAND`	The exact command exectuted
`NB_EXEC_ATTACHED_TO_CONTAINER`	Is this exec command attached to a container

*Require access to a container. Eg. When NB_EXEC_ATTACHED_TO_CONTAINER=true

💰 Tip: To use the enviornment variables in a docker-compose file, you will need to escape them with a double $:

labels:
  - "nautical-backup.curl.before=echo name: $$NB_EXEC_CONTAINER_NAME" # (1)!

Notice the double $$

🛎️ Want any additional enviornment variables? Submit an issue.

Executing a script

If you need to run more than a simple one-liner, we can run an entire script instead. Here is a basic example:

Create a file (we will name it script.sh) and place it in the mounted /config directory.

Remember: We mounted the /config folder as part of the Installation.

#!/usr/bin/env bash

echo "Hello from script.sh"

# Variable usage example
echo "NB_EXEC_CONTAINER_NAME: $NB_EXEC_CONTAINER_NAME" 
echo "NB_EXEC_CONTAINER_ID: $NB_EXEC_CONTAINER_ID"

Give the file execution permission: chmod +x /config/script.sh

Test the script

Ensure Nautical is running first, then run:

docker exec -it nautical-backup \
  /bin/bash /config/script.sh

Add your script to the label of your container's config

nautical-backup.exec.before=/config/script.sh

🔄 This is the same action as the Execute Commands variable, but applied only to this container.

Lifecycle Hooks¶

Lifecycle Hooks allow you to run a command inside the container that Nautical is backing up. This can be used to shutdown services and/or test for a successful restart.

Default: empty (no hooks)

FORMAT: docker exec format

nautical-backup.lifecycle.before=echo 'Hello from the container'
nautical-backup.lifecycle.after=/bin/sh ./script.sh

Test your lifecycle hooks

Before setting the label, it is a good idea to ensure it works first. Here is an example.

docker exec -it <container-name> echo 'Hello from the container'
docker exec -it <container-name> /bin/sh ./script.sh

Remember: ./script.sh is inside the container itself, not within Nautical.

Lifecycle Hook Timeouts¶

The default timeout for all lifecycle hooks is 60 seconds (60s). We can change this using another label.

Default: 60s

FORMAT: timeout command format (s for seconds, m for minutes h for hours, d for days, 0 to disable)

nautical-backup.lifecycle.before.timeout=1m
nautical-backup.lifecycle.after.timeout=0 # Disable timeout completely

Test your timeouts

You can test out the command timeout using the following format:

docker exec -it <container-name> timeout 0 echo 'Hello from the other side'
docker exec -it <container-name> timeout 1m /bin/sh ./script.sh

Use Default rsync Arguments¶

Use the default rsync arguments -raq (recursive, archive, quiet)

Useful when using Custom rsync Arguments

Default: none (use global setting)

nautical-backup.use-default-rsync-args=false

This label will override the global setting applied through Environment Variables

A value of true will use the default rsync arguments regardless of the global setting.
A value of false will not use the default rsync arguments regardless of the global setting.
Not setting the label value will use the global setting

🔄 Not setting a label is the same action as the Use Default rsync Arguments variable, but applied only to this container.

Custom rsync Arguments¶

Apply custom rsync args (in addition to the default args)

Default: empty (use global setting)

nautical-backup.rsync-custom-args=--exclude='*.log' --exclude='*.txt'

This label will override the global setting applied through Environment Variables

Any value will override the global rsync arguments configured through global settings.
A value of (space) "nautical-backup.rsync-custom-args= " will cancel any global setting for this container only.
Not setting the label value will use the global setting.

🔄 Not setting a label is the same action as the Custom rsync Arguments variable, but applied only to this container.