dockurr/portainer-backup

Sponsored OSS

By dockurr

Updated 14 days ago

Portainer Backup Utility

Image
Databases & Storage
Monitoring & Observability

4.3K

Portainer Backup

BuildVersionSizePackagePulls

Fork of Portainer Backup with some minor bugfixes and updated dependencies.

Features ✨

  • Backup the entire Portainer database
  • Backup the docker-compose files for stacks created in the Portainer web interface
  • Protect the archive file with a password

Usage 🐳

Via Docker Compose:

services:
  portainer-backup:
    container_name: portainer-backup
    image: dockurr/portainer-backup
    command: schedule
    environment:
      TZ: "America/New_York"
      PORTAINER_BACKUP_URL: "http://portainer:9000"
      PORTAINER_BACKUP_TOKEN: "PORTAINER_ACCESS_TOKEN"
      PORTAINER_BACKUP_PASSWORD: ""
      PORTAINER_BACKUP_OVERWRITE: 1
      PORTAINER_BACKUP_SCHEDULE: "0 0 0 * * *"
      PORTAINER_BACKUP_STACKS: 1
      PORTAINER_BACKUP_DRYRUN: 0
      PORTAINER_BACKUP_CONCISE: 1
      PORTAINER_BACKUP_DIRECTORY: "/backup"
      PORTAINER_BACKUP_FILENAME: "portainer-backup.tar.gz"
    volumes:
      - /var/backup:/backup
    restart: always

Via Docker CLI:

docker run -it --rm \
  --name portainer-backup \
  --volume $PWD/backup:/backup \
  --env PORTAINER_BACKUP_URL="http://portainer:9000" \
  --env PORTAINER_BACKUP_TOKEN="YOUR_ACCESS_TOKEN" \
  dockurr/portainer-backup \
  backup

Supported Commands & Operations ⚙️

This utility requires a single command to execute one of the built in operations.

CommandDescription
backupBackup portainer data archive
scheduleRun scheduled portainer backups
stacksBackup portainer stacks
testTest backup (no files are saved)
infoGet portainer server info
Backup

The backup operation will perform a single backup of the Portainer data from the specified server. This backup file will be TAR.GZ archive and can optionally be protected with a password (--password). The process will terminate immedately after the backup operation is complete.

The following docker command will perform a backup of the Portainer data.

docker run -it --rm \
  --name portainer-backup \
  --volume $PWD/backup:/backup \
  --env TZ="America/New_York" \
  --env PORTAINER_BACKUP_URL="http://portainer:9000" \
  --env PORTAINER_BACKUP_TOKEN="PORTAINER_ACCESS_TOKEN" \
  --env PORTAINER_BACKUP_OVERWRITE=true  \
  --env PORTAINER_BACKUP_DIRECTORY=/backup \
  dockurr/portainer-backup:latest \
  backup
Test

The test operation will perform a single backup of the Portainer data from the specified server. With the test operation, no data will be saved on the filesystem. The test operation is the same as using the --dryrun option. The process will terminate immedately after the test operation is complete.

The following docker command will perform a test of the Portainer data.

docker run -it --rm \
  --name portainer-backup \
  --volume $PWD/backup:/backup \
  --env TZ="America/New_York" \
  --env PORTAINER_BACKUP_URL="http://portainer:9000" \
  --env PORTAINER_BACKUP_TOKEN="PORTAINER_ACCESS_TOKEN" \
  --env PORTAINER_BACKUP_DIRECTORY=/backup \
  dockurr/portainer-backup:latest \
  test
Schedule

The schedule operation will perform continious scheduled backups of the Portainer data from the specified server. The --schedule option or PORTAINER_BACKUP_SCHEDULE environment variable takes a cron-like string expression to define the backup schedule. The process will run continiously unless a validation step fails immediately after startup.

The following docker command will perform a schedule of the Portainer data.

docker run -it --rm \
  --name portainer-backup \
  --volume $PWD/backup:/backup \
  --env TZ="America/New_York" \
  --env PORTAINER_BACKUP_URL="http://portainer:9000" \
  --env PORTAINER_BACKUP_TOKEN="PORTAINER_ACCESS_TOKEN" \
  --env PORTAINER_BACKUP_OVERWRITE=true  \
  --env PORTAINER_BACKUP_DIRECTORY=/backup \
  --env PORTAINER_BACKUP_SCHEDULE="0 0 0 * * *" \
  dockurr/portainer-backup:latest \
  schedule
Info

The info operation will perform an information request to the specified Portainer server. The process will terminate immedately after the info operation is complete.

The following docker command will perform a info request from the Portainer data.

docker run -it --rm \
  --name portainer-backup \
  --env PORTAINER_BACKUP_URL="http://portainer:9000" \
  dockurr/portainer-backup:latest \
  info
Stacks

The stacks operation will perform a single backup of the Portainer stacks docker-compose data from the specified server. This operation does not backup the Portainer database/data files, only the stacks. Alternatively you can include stacks backups in the backup operation using the --stacks option. The process will terminate immedately after the stacks operation is complete.

The following docker command will perform a stacks of the Portainer data.

docker run -it --rm \
  --name portainer-backup \
  --volume $PWD/backup:/backup \
  --env TZ="America/New_York" \
  --env PORTAINER_BACKUP_URL="http://portainer:9000" \
  --env PORTAINER_BACKUP_TOKEN="PORTAINER_ACCESS_TOKEN" \
  --env PORTAINER_BACKUP_OVERWRITE=true  \
  --env PORTAINER_BACKUP_DIRECTORY=/backup \
  dockurr/portainer-backup:latest \
  stacks
Restore

The backup file generated can be used with portainers built in restore function. See here for details: https://docs.portainer.io/admin/settings/general#restoring-from-a-local-file


Return Value

Portainer-backup will return a numeric value after the process exits.

ValueDescription
0Utility executed command successfully
1Utility encountered an error and failed

Command Line Options & Environment Variables

Portainer-backup supports both command line arguments and environment variables for all configuration options.

OptionEnvironment VariableTypeDescription
-t, --tokenPORTAINER_BACKUP_TOKENstringPortainer access token
-u, --urlPORTAINER_BACKUP_URLstringPortainer base url
-Z, --ignore-versionPORTAINER_BACKUP_IGNORE_VERSIONtrue|falseBypass portainer version check/enforcement
-d, --directory, --dirPORTAINER_BACKUP_DIRECTORYstringBackup directory/path
-f, --filenamePORTAINER_BACKUP_FILENAMEstringBackup filename
-p, --password, --pwPORTAINER_BACKUP_PASSWORDstringBackup archive password
-M, --mkdir, --make-directoryPORTAINER_BACKUP_MKDIRtrue|falseCreate backup directory path
-o, --overwritePORTAINER_BACKUP_OVERWRITEtrue|falseOverwrite existing files
-s, --schedule, --schPORTAINER_BACKUP_SCHEDULEstringCron expression for scheduled backups
-i, --include-stacks, --stacksPORTAINER_BACKUP_STACKStrue|falseInclude stack files in backup
-q, --quietPORTAINER_BACKUP_QUIETtrue|falseDo not display any console output
-D, --dryrunPORTAINER_BACKUP_DRYRUNtrue|falseExecute command task without persisting any data
-X, --debugPORTAINER_BACKUP_DEBUGtrue|falsePrint stack trace for any errors encountered
-J, --jsonPORTAINER_BACKUP_JSONtrue|falsePrint formatted/strucutred JSON data
-c, --concisePORTAINER_BACKUP_CONCISEtrue|falsePrint concise/limited output
-v, --version(N/A)Show utility version number
-h, --help(N/A)Show help

NOTE: If both an environment variable and a command line option are configured for the same option, the command line option will take priority.


Schedule Expression

Portainer-backup accepts a cron-like expression via the --schedule option or PORTAINER_BACKUP_SCHEDULE environment variable

NOTE: Additional details on the supported cron syntax can be found here: https://github.com/node-cron/node-cron/blob/master/README.md#cron-syntax

Syntax Format:

    ┌──────────────────────── second (optional)
    │   ┌──────────────────── minute
    │   │   ┌──────────────── hour
    │   │   │   ┌──────────── day of month
    │   │   │   │   ┌──────── month
    │   │   │   │   │   ┌──── day of week
    │   │   │   │   │   │
    │   │   │   │   │   │
    *   *   *   *   *   *

Examples:

    0   0   0   *   *   *   Daily at 12:00am
    0   0   5   1   *   *   1st day of month @ 5:00am
    0 */15  0   *   *   *   Every 15 minutes
Allowed field values
fieldvalue
second0-59
minute0-59
hour0-23
day of month1-31
month1-12 (or names)
day of week0-7 (or names, 0 or 7 are sunday)

Using multiples values

ExpressionDescription
0 0 4,8,12 * * *Runs at 4p, 8p and 12p

Using ranges

ExpressionDescription
0 0 1-5 * * *Runs hourly from 1 to 5

Using step values

Step values can be used in conjunction with ranges, following a range with '/' and a number. e.g: 1-10/2 that is the same as 2,4,6,8,10. Steps are also permitted after an asterisk, so if you want to say “every two minutes”, just use */2.

ExpressionDescription
0 0 */2 * * *Runs every 2 hours

Using names

For month and week day you also may use names or short names. e.g:

ExpressionDescription
* * * * January,September SundayRuns on Sundays of January and September
* * * * Jan,Sep SunRuns on Sundays of January and September

Filename & Directory Date/Time Substituions

Portainer-backup supports a substituion syntax for dynamically assigning date and time elements to the directory and filename options.

Command Line OptionEnvironment Variable
-d, --directory, --dirPORTAINER_BACKUP_DIRECTORY
-f, --filenamePORTAINER_BACKUP_FILENAME

All substitution presets and/or tokens are included in between double curly braces: {{ PRESET|TOKEN }}

Example:

  --filename "portainer-backup-{{DATE}}.tar.gz"

Portainer-backup uses the Luxon library for parting date and time syntax. Please see https://moment.github.io/luxon/#/formatting for more information.

All date and times are rendered in the local date/time of the system running the portainer-backup utility. Alternatively you can incude the UTC_ prefix in front of any of the tokens below to use UTC time instead.

Filenames are also processed through a sanitize funtion whick will strip characters that are not supported in filename. The : character is replaced with _ and the / character is replaced with -.

Supported Presets

The folllowing substition presets are defined by and supported in portainer-backup:

TokenFormatExample (US)
DATETIMEyyyy-MM-dd'T'HHmmss2022-03-05T231356
TIMESTAMPyyyyMMdd'T'HHmmss.SSSZZZ20220305T184827.445-0500
DATEyyyy-MM-dd2022-03-05
TIMEHHmmss231356
ISO8601yyyy-MM-dd'T'hh_mm_ss.SSSZZ2017-04-20T11_32_00.000-04_00
ISOyyyy-MM-dd'T'hh_mm_ss.SSSZZ2017-04-20T11_32_00.000-04_00
ISO_BASICyyyyMMdd'T'hhmmss.SSSZZZ20220305T191048.871-05_00
ISO_NO_OFFSETyyyy-MM-dd'T'hh_mm_ss.SSS2022-03-05T19_12_43.296
ISO_DATEyyyy-MM-dd2017-04-20
ISO_WEEKDATEyyyy-'W'kk-c2017-W17-7
ISO_TIMEhh_mm_ss.SSSZZZ11_32_00.000-04_00
RFC2822ccc, dd LLL yyyy HH_mm_ss ZZZThu, 20 Apr 2017 11_32_00 -0400
HTTPccc, dd LLL yyyy HH_mm_ss ZZZZThu, 20 Apr 2017 03_32_00 GMT
MILLISx1492702320000
SECONDSX1492702320.000
UNIXX1492702320.000
EPOCHX1492702320.000

The folllowing substition presets are provided my the Luxon library and are supported in portainer-backup: (See the following Luxon docs for more information: https://moment.github.io/luxon/#/formatting?id=presets)

(The following presets are using the October 14, 1983 at 13:30:23 as an example.)

NameDescriptionExample in en_USExample in fr
DATE_SHORTshort date10/14/198314/10/1983
DATE_MEDabbreviated dateOct 14, 198314 oct. 1983
DATE_MED_WITH_WEEKDAYabbreviated date with abbreviated weekdayFri, Oct 14, 1983ven. 14 oct. 1983
DATE_FULLfull dateOctober 14, 198314 octobre 1983
DATE_HUGEfull date with weekdayFriday, October 14, 1983vendredi 14 octobre 1983
TIME_SIMPLEtime1:30 PM13:30
TIME_WITH_SECONDStime with seconds1:30:23 PM13:30:23
TIME_WITH_SHORT_OFFSETtime with seconds and abbreviated named offset1:30:23 PM EDT13:30:23 UTC−4
TIME_WITH_LONG_OFFSETtime with seconds and full named offset1:30:23 PM Eastern Daylight Time13:30:23 heure d’été de l’Est
TIME_24_SIMPLE24-hour time13:3013:30
TIME_24_WITH_SECONDS24-hour time with seconds13:30:2313:30:23
TIME_24_WITH_SHORT_OFFSET24-hour time with seconds and abbreviated named offset13:30:23 EDT13:30:23 UTC−4
TIME_24_WITH_LONG_OFFSET24-hour time with seconds and full named offset13:30:23 Eastern Daylight Time13:30:23 heure d’été de l’Est
DATETIME_SHORTshort date & time10/14/1983, 1:30 PM14/10/1983 à 13:30
DATETIME_MEDabbreviated date & timeOct 14, 1983, 1:30 PM14 oct. 1983 à 13:30
DATETIME_FULLfull date and time with abbreviated named offsetOctober 14, 1983, 1:30 PM EDT14 octobre 1983 à 13:30 UTC−4
DATETIME_HUGEfull date and time with weekday and full named offsetFriday, October 14, 1983, 1:30 PM Eastern Daylight Timevendredi 14 octobre 1983 à 13:30 heure d’été de l’Est
DATETIME_SHORT_WITH_SECONDSshort date & time with seconds10/14/1983, 1:30:23 PM14/10/1983 à 13:30:23
DATETIME_MED_WITH_SECONDSabbreviated date & time with secondsOct 14, 1983, 1:30:23 PM14 oct. 1983 à 13:30:23
DATETIME_FULL_WITH_SECONDSfull date and time with abbreviated named offset with secondsOctober 14, 1983, 1:30:23 PM EDT14 octobre 1983 à 13:30:23 UTC−4
DATETIME_HUGE_WITH_SECONDSfull date and time with weekday and full named offset with secondsFriday, October 14, 1983, 1:30:23 PM Eastern Daylight Timevendredi 14 octobre 1983 à 13:30:23 heure d’été de l’Est

Acknowledgements 🙏

Special thanks to @SavageSoftware for creating the original project.

Stars 🌟

Stars

Docker Pull Command

docker pull dockurr/portainer-backup