These examples used Docker Compose syntax. See the Installation section to fit them into your configuration.
+Remember the folder naming convention
+container-name must match the source and destination folder names.Don't have all your container volumes in the same directory? That's okay, we can use Docker volume mappings to help.
+This config allows additional volumes outside the traditional source directory.
volumes:
+ # Standard config
+ - /var/run/docker.sock:/var/run/docker.sock
+ - /source:/app/source
+ - /destination:/app/destination
+ # Alternative source directories examples
+ - /opt/pihole:/app/source/pihole #(1)!
+ - /mnt/docker_volumes/plex:/app/source/plex #(2)!
+source directorysource directoryWe added 2 additional source volumes: pihole and plex. The end result will have a source directory inside the Nautical container that looks like this:
<Nautical Backup>/app/source:
+- container1-data #(1)!
+- container2-data #(2)!
+- pihole # Mapped from /opt/pihole
+- plex # Mapped from /mnt/docker_volumes/plex
+/source directory/source directoryThis config uses volumes only outside the traditional source directory.
volumes:
+ # Standard config
+ - /var/run/docker.sock:/var/run/docker.sock
+ - /destination:/app/destination #(1)!
+ # Alternative source directories examples
+ - /opt/pihole:/app/source/pihole
+ - /opt/trilium:/app/source/trilium
+ - /mnt/docker_volumes/plex:/app/source/plex
+ - /var/data/portainer:/app/source/portainer
+source directories, the destination directories will all be the same:
+ /destination/pihole
+/destination/trilium
+/destination/plex
+/destination/portainer
+This configuration allows us to map as many container data folders as we'd like from any source directory. +
<Nautical Backup>/app/source:
+- pihole # Mapped from /opt/pihole
+- trilium # Mapped from /opt/trilium
+- plex # Mapped from /mnt/docker_volumes/plex
+- portainer # Mapped from /var/data/portainer
+We can also remap the destination directory for any container we'd like.
+volumes:
+ # Standard config
+ - /var/run/docker.sock:/var/run/docker.sock
+ - /source:/app/source #(1)!
+ - /destination:/app/destination
+ # Alternative destination directories examples
+ - /opt/pihole-backup:/app/destination/pihole
+ - /mnt/docker_volume-backups/plex:/app/destination/plex
+destination directories, the source directories are using the standard configuration:
+ /source/pihole
+/source/plex
+This config allows the addition of volumes outside the traditional destination directory.
We added 2 additional destination volumes: pihole and plex. The end result will have a destination directory inside the Nautical container that looks like this:
<Nautical Backup>/app/destination:
+- container1-data #(1)!
+- container2-data #(2)!
+- pihole # Mapped to /opt/pihole-backup
+- plex # Mapped to /mnt/docker_volume-backups/plex
+/source directory/source directoryvolumes:
+ # Standard config
+ - /var/run/docker.sock:/var/run/docker.sock
+ - /source:/app/source #(1)!
+ # Alternative destination directories examples
+ - /opt/pihole:/app/destination/pihole
+ - /opt/trilium:/app/destination/trilium
+ - /mnt/docker_volumes/plex:/app/destination/plex
+ - /var/data/portainer:/app/destination/portainer
+destination directories, the source directories will all be the same:
+ /source/pihole
+/source/trilium
+/source/plex
+/source/portainer
+This configuration allows us to map as many container data folders as we'd like to any destination directory. +
<Nautical Backup>/app/destination:
+- pihole # Mapped to /opt/pihole
+- trilium # Mapped to /opt/trilium
+- plex # Mapped to /mnt/docker_volumes/plex
+- portainer # Mapped to /var/data/portainer
+
Homepage is a modern, fully static, fast, secure fully proxied, highly customizable application dashboard with integrations for over 100 services and translations into multiple languages. Easily configured via YAML files or through docker label discovery.
+
We are going to take advantage of Homepage's Custom API Widget to get the following result:
+
Our configuration will look something like this:
+- Nautical Backup:
+ icon: https://raw.githubusercontent.com/Minituff/nautical-backup/main/docs/media/Logo-large.png
+ description: Docker Volume Backups
+ widget:
+ type: customapi
+ url: http://<nautical-ip>:8069/api/v1/nautical/dashboard
+ username: admin
+ password: password
+ method: GET
+ mappings:
+ - field: number_of_containers
+ label: Total Containers
+
+ - field: completed
+ label: Completed
+
+ - field: skipped
+ label: Skipped
+
+ - field: errors
+ label: errors
+
+ - field: last_cron
+ label: Last Run
+ format: relativeDate # (1)!
+
+ - field: next_cron
+ label: Next Run
+Here, you can set an additional property called format to one of these options:
relativeDate example: 10 hours agodate removes the exact time and shows the day onlyYou can also add this to the next_cron field.
It is recommended that you don't enable all the fields. Just comment out the fields that you don't need.
+{
+ "next_cron": {
+ "1": [
+ "Monday, April 22, 2024 at 05:00 AM",
+ "04/22/24 05:00"
+ ],
+ "2": [
+ "Tuesday, April 23, 2024 at 05:00 AM",
+ "04/23/24 05:00"
+ ],
+ "3": [
+ "Wednesday, April 24, 2024 at 05:00 AM",
+ "04/24/24 05:00"
+ ],
+ "4": [
+ "Thursday, April 25, 2024 at 05:00 AM",
+ "04/25/24 05:00"
+ ],
+ "5": [
+ "Friday, April 26, 2024 at 05:00 AM",
+ "04/26/24 05:00"
+ ],
+ "cron": "0 5 * * *",
+ "tz": "America/Los_Angeles"
+ },
+ "last_cron": "04/21/24 05:00",
+ "next_run": "04/22/24 05:00",
+ "number_of_containers": 33,
+ "completed": 25,
+ "skipped": 8,
+ "errors": 0,
+ "backup_running": 8
+}
+Nautical itself does not have the ability to map network shares. However, it can use a network share for either the source or destination.
+Commonly, we run containers on our host machine, then use an NFS share as the backup destination location. This page will give a brief overview of how to do that.
+Create the NFS destination directories. +
# Create mount point (1)
+mkdir -p /mnt/nfs/docker_backups
+Setup NFS mount points: +
nano /etc/fstab
+# | ------------- Source -------------- | ---- Destination ---- | -------- Options ---------- |
+192.168.1.10:/mnt/backups/docker_volumes /mnt/nfs/docker_backups nfs _netdev,auto,rw,async 0 0
+192.168.1.10 is just an example IP address
+Apply and mount the NFS shares +
mount -a
+A successful mount -a will return nothing in the console
Verify read and write access +
cd /mnt/nfs/docker_backups
+touch test.txt && rm test.txt
+The above example created a local directory of /mnt/nfs/docker_backups which is an NFS share pointing to 192.168.1.10:/mnt/backups/docker_volumes.
Here is how we can use this new mount withing Nautical:
+services:
+ nautical-backup:
+ image: minituff/nautical-backup:2.9 #(7)!
+ container_name: nautical-backup
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock #(1)!
+ - /config:/config #(9)!
+ - /source:/app/source #(2)!
+ - /mnt/nfs/docker_backups:/app/destination #(3) <-- NFS Share
+source directory.destination directory.0 4 * * * - Every day at 4am.latest tag.docker run -d \
+ --name nautical-backup \
+ -v /var/run/docker.sock:/var/run/docker.sock \ #(1)!
+ -v /config:/config \ #(9)!
+ -v /mnt/nfs/docker_backups:/app/destination \ #(2)!
+ -e SKIP_CONTAINERS="example1,example2,example3" \ #(6)!
+ minituff/nautical-backup:2.9 #(7)!
+source directory.destination directory.0 4 * * * - Every day at 4am.latest tag.Nautical does not provide connectivity to remote services such as S3, B2, or Google Drive. We believe there are better tools for these jobs and think it is best not to recreate them.
+Nautical can backup to an NFS share though, we have detailed steps to do this here.
+Here is a list of a few of our favorite remote backup solutions:
+Ideally, you would configure Nautical to create a backup at a destination folder, then point that folder to a remote backup solution.
Nautical provides configuration in the form of Docker environment variables.
+See the Installation Section, which contains a few examples of applying environment variables.
+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.
+
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
+docker exec nautical-backup date
+Allow changing the schedule for when the backup is started.
+++Default: 0 4 * * *
+
CRON_SCHEDULE=0 4 * * *
+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
+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
+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.
Use this option to designate which path strategy is used when creating a dated destination directory.
+date/container = /dest_folder/2024-04-05/container1container/date = /dest_folder/container1/2024-04-05++Default: date/container
+Options:
+container/dateordate/container
DEST_DATE_PATH_FORMAT=date/container
+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
+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
+2024-11-24_14-26-43 folderBy 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.
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
+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
+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)!
+additional inside the /app/source directory in the containeradditional and additional2 foldersbefore is the defaultadditional2 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.
+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.
+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
+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)!
+/nautical/destination1 directory in the container/nautical/destination2 directory in the contianer/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 machineAdditional Folders will also be copied to these secondary locations.
+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)
+
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-truncdocker inspect <container name>🔄 This is the same action as the Disable Nautical label, but applied globally.
+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.
+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.
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
+| 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
+| 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.
+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.
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 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
+execBefore 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'
+| 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)!
+$$🛎️ Want any additional enviornment variables? Submit an issue.
+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).
+Enable or Disable the automatically generated report file.
+++Default: true
+
REPORT_FILE=true
+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.
+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.
+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 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
+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.
+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.
+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.
Set the console log level for the container.
+++Default: INFO
+Options: TRACE, DEBUG, INFO, WARN, ERROR
+
LOG_LEVEL=INFO
+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
+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 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.
+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.
# 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.
+
+