Environment Variables

Nautical provides configuration in the form of Docker environment variables.

See the Installation Section, which contains a few examples of applying environment variables.

Environment Variable vs Label 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.

Time Zone¶

Sets the time-zone to be used by the CRON schedule. If this environment variable is not set, Nautical will use the default time-zone: Etc/UTC.

To change the time-zone, see this Wikipedia page, find your location and use the value in TZ Database Name, e.g America/Los_Angeles.

Default: Etc/UTC

TZ=America/Los_Angeles

To verify the correct time-zone, use the command docker exec nautical-backup date

CRON Schedule¶

Allow changing the schedule for when the backup is started.

Default: 0 4 * * *

CRON_SCHEDULE=0 4 * * *

Enable/Disable CRON Schedule¶

Completely disable the recurring backup via a CRON schedule.

This could be useful if you want to run Nautical manually via Backup On Start or the Rest API.

Default: true (CRON enabled)

CRON_SCHEDULE_ENABLED=false

Create a Dated Destination Folder¶

This option will tell Nautical to create a new destination folder on backup.

For example: /dest_folder/2024-04-05/contianer

Default: false

USE_DEST_DATE_FOLDER=true

Destination Folder Format¶

Use the Python time.strftime() module to format format the destination folder's name.

Default: %Y-%m-%d (2024-04-05 for example)

Format: Python time.strftime() format

DEST_DATE_FORMAT=Nautical_Backup-%Y-%m-%d

You are allowed to use almost anything in this field

While it may be a intended to use the date format here, you don't have to. You could set this value to latest backup or insert addional text around the date format like this: Nautical Backup - %Y-%m-%d. Use this setting to add a prefix and/or suffix to the dated folder.

NOTE: Some linux machines may have issues with spaces in this field. It is recommended you use underscores _ instead of spaces when possible.

Destination Folder Path¶

Use this option to designate which path strategy is used when creating a dated destination directory.

date/container = /dest_folder/2024-04-05/container1
container/date = /dest_folder/container1/2024-04-05

Default: date/container

Options: container/date or date/container

DEST_DATE_PATH_FORMAT=date/container

Container Backup Date vs Nautical Start Date¶

Use the precise date for formatting the destination folder When false, use the time Nautical started the backup (not when the container was backed up).

Default: false

USE_CONTAINER_BACKUP_DATE=true

Understanding USE_CONTAINER_BACKUP_DATE.

Let's say you have the following format: DEST_DATE_FORMAT=%Y-%m-%d_%H-%M-%S

Since the timing is so precise (using seconds) we may get a result like this:

-- src
|-- 2024-11-24_14-26-43
|-- 2024-11-24_14-26-44
|-- 2024-11-24_14-28-10

But what we actually want is a result like this:

-- src
|-- 2024-11-24_14-26-43
#  (1)
|-- 2024-11-24_14-28-10

The folder that was here is now within in 2024-11-24_14-26-43 folder

By setting USE_CONTAINER_BACKUP_DATE=false, then the date used will be the time Nautical actually started, not the time when each container is processed. Meaning that even if the containers take a few minutes to backup, the folder format will remain the same for each of them.

Additional Folders¶

Allows Nautical to backup folders that are not associated with containers.

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

Default: empty (no additional folders)

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

ADDITIONAL_FOLDERS=folder1,folder_name2

When to backup additional folders?¶

Use this setting to decide if the additional folders are backed up before or after the containers.

Default: before

Options: before, after

ADDITIONAL_FOLDERS_WHEN=after

Additional Folders Example

This example shows us how to add two additional folders to our backup that are not associated with a container. Here, the additional folders will be backed up first, followed by any containers Nautical finds.

The additional2 folder already exists within the /opt/volume-data so it does not need a mount point.

services:
  nautical-backup:
    image: minituff/nautical-backup:2.9
    container_name: nautical-backup
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /config:/config
      - /opt/volume-data:/app/source #(4)!
      - /mnt/nfs-share/backups:/app/destination
      - /mnt/additional:/app/source/additional #(1)!
    environment:
      - ADDITIONAL_FOLDERS=additional,additional2 #(2)!
      - ADDITIONAL_FOLDERS_WHEN=before #(3)!

Mount additional inside the /app/source directory in the container
Tell Nautical to process both the additional and additional2 folders
Tell Nautical when to backup the additional folders. * before is the default
The additional2 folder already exists within the /opt/volume-data so it does not need a mount point.

If the same folder is named in the Additional Folders label and a service env variable--it will be backed up twice.

🔄 This is the same action as the Additional Folders label, but applied globally.

Additional folders date format¶

To enable the Dated Destination folder syntax for Global Additional folders (not folders tied to containers), then use this variable.

Default: false (use the base destination folder)

ADDITIONAL_FOLDERS_USE_DEST_DATE_FOLDER=true

The destination folder format and destination folder path enviornment variables will be respected.

Secondary Destination Locations¶

Tell Nautical to backup folders to more destination locations--in addition to the normal destination folder (/app/destination).

This is a path inside the Nautical container.

Default: empty (no secondary locations)

Format: <absolute paths> (comma separated for multiple items)

SECONDARY_DEST_DIRS=/path/one,/path/two

Example 1

Pay attention to the newly added highlighed lines:

services:
  nautical-backup:
    image: minituff/nautical-backup:2.9
    container_name: nautical-backup
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /config:/config
      - /opt/volume-data:/app/source
      - /mnt/nfs-share/backups:/app/destination
      - /mnt/nfs-share/destination1:/nautical/destination1 #(1)!
      - /another/path:/nautical/destination2 #(2)!
      environment:
      - SECONDARY_DEST_DIRS=/nautical/destination1,/nautical/destination2 #(3)!

Mount /nautical/destination1 directory in the container
Mount /nautical/destination2 directory in the contianer
Tell Nautical to copy files to these two locations:
- /nautical/destination1 which actually goes to /mnt/nfs-share/destination1 on the host machine
- /nautical/destination2 which actually goes to /another/path on the host machine

Additional Folders will also be copied to these secondary locations.

Skip Containers¶

Tell Nautical to skip backup of containers in this list.

This list can either be the container name or full id.

Default: empty (no skips)

Example 1Example 2

SKIP_CONTAINERS=container-name1,container-name2,container-name3

SKIP_CONTAINERS=container-name1,056bd2e970c1338782733fdbf1009c6e158c715d0d105b11de88bd549430e7f5

Getting the full container ID

Usually, it's easier to just use the container-name, but if you need to use the full ID, these commands will help:

docker ps --no-trunc
docker inspect <container name>

🔄 This is the same action as the Disable Nautical label, but applied globally.

Require Label¶

Require the Docker Label nautical-backup.enable=true to be present on each container or it will be skipped.

Default: false

REQUIRE_LABEL=true

See the Enable or Disable Nautical Label Section for more details.

Override Source Directory¶

Allows a source directory and container-name that do not match.

Default: empty (use container name)

Format: <container-name>:<local source folder name> (comma separated for multiple items)

Normally a container is backed up only when the container-name is the exact same as the source folder name.

Example 1Example 2Example 3

For example, a container named Pi.Alert will be skipped with a source directory name of pialert. To fix this, we can override the source directory name so that it does not need to match the container name.

OVERRIDE_SOURCE_DIR=Pi.Alert:pialert

We can override multiple containers if we separate them with a comma.

OVERRIDE_SOURCE_DIR=example1:example1-new-source-data,ctr2:ctr2-new-source

The example above would yield the following results:

Container Name	Old Source Directory	New Source Directory
example1	`src/example1`	`src/example1-new-source-data`
ctr2	`src/ctr2`	`src/ctr2-new-source`

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

OVERRIDE_SOURCE_DIR=example1:subfolder/example1

The example above would yield the following results:

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

🔄 This is the same action as the Override Source Directory label, but applied globally.

Override Destination Directory¶

Changes the destination backup name to be something other than the container name.

Default: empty (use container name)

Format: <container-name>:<new destination folder name> (comma separated for multiple items)

Normally, a container is backed to a folder with the same name as the container-name.

Example 1Example 2

For example, let's say we have a container named Pi.Alert. By default, the container will be backed up to a folder named Pi.Alert. If we want to change this destination folder name to be pialert, we can do that using overrides.

OVERRIDE_DEST_DIR=Pi.Alert:pialert

OVERRIDE_DEST_DIR=example1:example1-new-dest-data,ctr2:newdest

The example above would yield the following results:

Container Name	Old Destination Directory	New Destination Directory
example1	`dest/example1`	`dest/example1-new-dest-data`
ctr2	`dest/ctr2`	`dest/newdest`

🔄 This is the same action as the Override Destination Directory label, but applied globally.

Execute Commands before or after backup¶

Execute a command before or after backing up all the containers. This can be used to alert services before shutdown and/or ensure the services came online correctly.

This command will run before/after the entire backup process is initiated.

Default: empty (nothing will be done)

FORMAT: The entirety of a command

PRE_BACKUP_EXEC=/config/prepare-for-backup.sh
POST_BACKUP_EXEC=curl -d "Backup successful 😀" ntfy.sh/mytopic

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 enviornment variable

PRE_BACKUP_EXEC=/config/script.sh

🔄 This is the same action as the Execute Commands label, but applied globally (not per container).

Report file¶

Enable or Disable the automatically generated report file.

Default: true

REPORT_FILE=true

Skip Stopping Containers¶

Bypass stopping the container before performing a backup. This can be useful for containers with minimal configuration.

Default: empty (no containers will be skipped)

SKIP_STOPPING=example1,example2

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 the same action as the Stop Before Backup label, but applied globally.

Backup on Start¶

Nautical will immediately perform a backup when the container is started in addition to the CRON scheduled backup.

Default: false

BACKUP_ON_START=true

The console Nautical backup logs will not be avilable until all the containers have been processed.

This is due to a limitation in S6-Overlay.

Run Once¶

This variable will tell Nautical to immediately quit after the first backup. If combined with Backup on Start, Nautical will immediately start a backup, then exit.

Default: false

RUN_ONCE=true

Without Backup on Start, the CRON Schedule will call the backup and then Nautical will exit.

Mirror Source Directory Name to Destination¶

Mirror the source folder name to the destination folder name.

When using a source directory override, then the 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 override.

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: true

KEEP_SRC_DIR_NAME=false

Example 1Example 2Example 3

OVERRIDE_SOURCE_DIR=Pi.Alert:pialert

Here we override the source folder to Pi.Alert to pialert, and since KEEP_SRC_DIR_NAME=true (which is the default) the destination folder will also be named pialert.

Container Name	Source Directory	Destination Directory
Pi.Alert	`src/pialert`	`destination/pialert`

KEEP_SRC_DIR_NAME=false
OVERRIDE_SOURCE_DIR=Pi.Alert:pialert

Here we override the source folder to Pi.Alert to pialert, and since KEEP_SRC_DIR_NAME=false the destination folder will not be mirrored, so the container-name Pi.Alert will be used.

Container Name	Source Directory	Destination Directory
Pi.Alert	`src/pialert`	`destination/Pi.Alert`

OVERRIDE_SOURCE_DIR=Pi.Alert:pialert
OVERRIDE_DEST_DIR=Pi.Alert:pialert-backup

Here we override the source folder to Pi.Alert to pialert.

We also override the destination folder to pialert-backup.

Since a destination override is used, the KEEP_SRC_DIR_NAME setting is not used for this container.

Container Name	Source Directory	Destination Directory
Pi.Alert	`src/Pi.Alert`	`destination/pialert-backup`

🔄 This is the same action as the Mirror Source Directory Name to Destination label, but applied globally.

HTTP REST API¶

Enable or disable the Nautical API.

Default: true

HTTP_REST_API_ENABLED=false

A quick note

A false value doesn't completely disable the REST API service--it will only disable the logs stating the API starting.

The REST API is used internally for Docker Healthchecks. However, you do not open the port, then all the endpoints will remain unreachable. See the Nautical API section for more information.

API Username and Password¶

See API Section for examples how authenticating to the API.

Default Username: admin

Default Password: admin

Format: string

HTTP_REST_API_USERNAME=admin
HTTP_REST_API_PASSWORD=password

Setting the username and password to "" will not disable authentication. A login is always required.

Console Log Level¶

Set the console log level for the container.

Default: INFO

Options: TRACE, DEBUG, INFO, WARN, ERROR

LOG_LEVEL=INFO

Report Log Level¶

Set the log level for the generated report file. Only used if the report file is enabled.

Default: INFO

Options: TRACE, DEBUG, INFO, WARN, ERROR

REPORT_FILE_LOG_LEVEL=INFO

Use Report File on Backup Only¶

With a value of true, then the report file will only be created when a backup is performed, not during Nautical initialization.

With a value of false, then all logs will also be sent to the report file assuming they are the right log level.

Default: true

REPORT_FILE_ON_BACKUP_ONLY=false

Use Default rsync Arguments¶

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

Useful when using Custom rsync Arguments

Default: true

USE_DEFAULT_RSYNC_ARGS=false

🔄 This is the same action as the Use Default rsync Arguments label, but applied globally.

Custom rsync Arguments¶

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

Default: empty (no custom rsync args will be applied)

There are many rsync arguments that be be used here.

Custom rsync Arguments Example

# Don't backup any .log or any .txt files
RSYNC_CUSTOM_ARGS=--exclude='*.log' --exclude='*.txt'

The RSYNC_CUSTOM_ARGS will be inserted after the $DEFAULT_RSYNC_ARGS as shown:

rsync $DEFAULT_RSYNC_ARGS $RSYNC_CUSTOM_ARGS $src_dir/ $dest_dir/

🔄 This is the same action as the Custom rsync Arguments label, but applied globally.