Portainer Backup

(Developed with ♥ by SavageSoftware, LLC.)

Overview

A utility for scripting or scheduling Portainer backups. This utility can backup the entire Portainer database, optionally protect the archive file with a password and can additionally backup the docker-compose files for stacks created in the Portainer web interface.

Table of Contents

• Overview
• TL;DR
• Prerequisites
• Installation
• Supported Commands & Operations
  • Backup
  • Test
  • Schedule
  • Info
  • Stacks
  • Restore
• Return Value
• Command Line Options & Environment Variables
• Schedule Expression
• Filename & Directory Date/Time Substituions
  • Supported Presets
  • Supported Tokens
• Command Line Help
• Docker Compose

TL;DR

NodeJS & NPM

Command to install portainer-backup using node's NPM command:

npm install --global portainer-backup   

Command to launch portainer-backup after installing with NPM to perform a backup of your portainer server:

portainer-backup \
  backup \
  --url "http://portainer:9000" \
  --token "PORTAINER_ACCESS_TOKEN" \
  --directory $PWD/backup  

NPX

Command to install & launch portainer-backup using node's NPX command to perform a backup of your portainer server:

npx portainer-backup \
  backup \
  --url "http://portainer:9000" \
  --token "PORTAINER_ACCESS_TOKEN" \
  --directory $PWD/backup  

DOCKER

Command to launch portainer-backup using a Docker container to perform a backup of your portainer server:

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" \
  savagesoftware/portainer-backup:latest \
  backup

Supported Docker platforms:

• linux/amd64 (Intel/AMD x64)
• linux/arm64 (ARMv8)
• linux/arm (ARMv7)

Prerequisites

Portainer-backup requires the following prerequisites:

This utility has only been tested on Portainer v2.11.0 and later.

NOTE: If attempting to use with an older version of Portainer this utility will exit with an error message. While it is untested, you can use the --ignore-version option to bypass the version validation/enforcement.

You will need to obtain a Portiner Access Token from your Portainer server from an adminstrative user account.

Installation

Command to install portainer-backup using node's NPM command:

npm install --global portainer-backup   

Supported Commands & Operations

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

NOTE: The restore command is not currently implemented due to issues with the Portainer API.

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 command will perform a backup of the Portainer data.

portainer-backup \
  backup \
  --url "http://portainer:9000" \
  --token "PORTAINER_ACCESS_TOKEN" \
  --directory $PWD/backup \
  --overwrite

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 \
  savagesoftware/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 command will perform a test of the Portainer data.

portainer-backup \
  test \
  --url "http://portainer:9000" \
  --token "PORTAINER_ACCESS_TOKEN" \
  --directory $PWD/backup

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 \
  savagesoftware/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 command will perform a test of the Portainer data.

portainer-backup \
  schedule \
  --url "http://portainer:9000" \
  --token "PORTAINER_ACCESS_TOKEN" \
  --directory $PWD/backup \
  --overwrite \
  --schedule "0 0 0 * * *"

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 * * *" \
  savagesoftware/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 command will perform a info from the Portainer server.

portainer-backup info --url "http://portainer:9000"

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" \
  savagesoftware/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 command will perform a stacks of the Portainer data.

portainer-backup \
  backup \
  --url "http://portainer:9000" \
  --token "PORTAINER_ACCESS_TOKEN" \
  --directory $PWD/backup \
  --stacks

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 \
  savagesoftware/portainer-backup:latest \
  stacks

Restore

The restore operation is not implemented at this time. We encountered trouble getting the Portainer restore API (https://app.swaggerhub.com/apis/portainer/portainer-ce/2.11.1#/backup/Restore) to work properly and are investigating this issue further.

Return Value

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

Command Line Options & Environment Variables

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

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

Using multiples values

Using ranges

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.

Using names

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

Filename & Directory Date/Time Substituions

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

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:

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.)

Supported Tokens

If one of the substitution presets does not meet your needs, you can build your own date/time string using the supported tokens listed below. (See the following Luxon docs for more information: https://moment.github.io/luxon/#/formatting?id=table-of-tokens)

Example:

  --filename "portainer-backup-{{yyyy-MM-dd}}.tar.gz"

(Examples below given for 2014-08-06T13:07:04.054 considered as a local time in America/New_York.)

Command Line Help

Use the help command or --help option to see a listing of command line options directly via the CLI.

  ___         _        _                ___          _             
 | _ \___ _ _| |_ __ _(_)_ _  ___ _ _  | _ ) __ _ __| |___  _ _ __ 
 |  _/ _ \ '_|  _/ _` | | ' \/ -_) '_| | _ \/ _` / _| / / || | '_ \
 |_| \___/_|  \__\__,_|_|_||_\___|_|   |___/\__,_\__|_\_\\_,_| .__/
                                                             |_|   
┌──────────────────────────────────────────────────────────────────┐
│   Made with ♥ by SavageSoftware, LLC © 2022    (Version 0.0.6)   │
└──────────────────────────────────────────────────────────────────┘

Usage: <command> [(options...)]

Commands:
  portainer-backup backup              Backup portainer data
  portainer-backup schedule            Run scheduled portainer backups
  portainer-backup stacks              Backup portainer stacks
  portainer-backup info                Get portainer server info
  portainer-backup test                Test backup data & stacks (backup --dryru
                                       n --stacks)
  portainer-backup restore <filename>  Restore portainer data
  portainer-backup help                Show help
  portainer-backup version             Show version

Portainer Options:
  -t, --token           Portainer access token
          [string]                                                 [default: ""]
  -u, --url             Portainer base url
                                     [string] [default: "http://portainer:9000"]
  -Z, --ignore-version  Bypass portainer version check/enforcement
                                                      [boolean] [default: false]

Backup Options:  (applies only to 'backup' command)
  -d, --directory, --dir          Backup directory/path
                                                   [string] [default: "/backup"]
  -f, --filename                  Backup filename
                                   [string] [default: "portainer-backup.tar.gz"]
  -p, --password, --pwd           Backup archive password [string] [default: ""]
  -o, --overwrite                 Overwrite existing files
                                                      [boolean] [default: false]
  -M, --mkdir, --make-directory  Create backup directory path if needed
                                                      [boolean] [default: false]
  -s, --schedule, --sch           Cron expression for scheduled backups
                                             [string] [default: "0 0 0 * * * *"]
  -i, --include-stacks, --stacks  Include stack files in backup
                                                      [boolean] [default: false]

Stacks Options:  (applies only to 'stacks' command)
  -d, --directory, --dir  Backup directory/path    [string] [default: "/backup"]
  -o, --overwrite         Overwrite existing files    [boolean] [default: false]
  -M, --mkdir, --make-directory  Create backup directory path if needed
                                                      [boolean] [default: false]
Restore Options:  (applies only to 'restore' command)
  -p, --password, --pwd  Backup archive password          [string] [default: ""]

Options:
  -h, --help     Show help                                             [boolean]
  -q, --quiet    Do not display any console output    [boolean] [default: false]
  -D, --dryrun   Execute command task without persisting any data.
                                                      [boolean] [default: false]
  -X, --debug    Print details stack trace for any errors encountered
                                                      [boolean] [default: false]
  -J, --json     Print formatted/strucutred JSON data [boolean] [default: false]
  -c, --concise  Print concise/limited output         [boolean] [default: false]
  -v, --version  Show version number                                   [boolean]

Command Examples:
  info     --url http://192.168.1.100:9000

  backup   --url http://192.168.1.100:9000
           --token XXXXXXXXXXXXXXXX
           --overwrite
           --stacks

  stacks   --url http://192.168.1.100:9000
           --token XXXXXXXXXXXXXXXX
           --overwrite

  restore  --url http://192.168.1.100:9000
           --token XXXXXXXXXXXXXXXX
           ./file-to-restore.tar.gz

  schedule --url http://192.168.1.100:9000
           --token XXXXXXXXXXXXXXXX
           --schedule "0 0 0 * * *"

Schedule Expression Examples: (cron syntax)

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

    0   0   0   *   *   *   Daily at 12:00am
    0   0   5   1   *   *   1st day of month @ 5:00am
    0 */15  0   *   *   *   Every 15 minutes

    Additional Examples @ https://github.com/node-cron/node-cron#cron-syntax

Docker Compose

Alternatively you can use a docker-compose.yml file to launch your portainer-backup container. Below is a sample docker-compose.yml file you can use to get started:

version: '3.8'
services:
  portainer-backup:
    container_name: portainer-backup
    image: savagesoftware/portainer-backup:latest
    hostname: portainer-backup
    restart: unless-stopped
    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

Just run the docker-compose up -d command in the same directory as your docker-compose.yml file to launch the container instance.

Supported Docker platforms:

• linux/amd64 (Intel/AMD x64)
• linux/arm64 (ARMv8)
• linux/arm (ARMv7)