backpack

README

Backpack

Backs up your directories periodically with special handling like snapshoting sqlite file.

When running self-hosting applications, backup is important and we often find different application has different backing up strategies. Simply copying stuff may not be good for applications using database files (e.g. sqlite). Backpack offers a way to specify different rules to snapshot different applications using directory rule and regex-based file rules, and then it uses librclone to backup your files to storage platforms that you wish to backup your files.

Version

v0.1

How to use?

Run directly

Run the binary directly with the following command line arguments:

-config string
    config file path (required)
-try-first
    try backup before running cron
-try-only
    try backup only without starting cron
-version
    show version

For example ./backpack -config config.json -try-first. The config file is a JSON file structured as the following format:

{
    // Config version (optional)
    "version": "0.1",
    // Backup rules
    "backups": [
        {
            // List directories to backup with their own rules
            "directories": [
                {
                    // Directory path
                    "path": "/data/run_files",
                    // Rules for file
                    "file_rules": [
                        {
                            // Regular expression for all files ending in `sqlite3`
                            "regex": ".*sqlite3",
                            // Snapshots these files using `sqlite3 .backup`
                            "command": "sqlite"
                        },
                        {
                            // The regular expression matches relative path in directory path
                            // The file rules are matched in order, the first matched rule
                            // will be executed
                            "regex": "files/\.unwanted/.*",
                            // Ignore these files
                            "command": "ignore"
                        }
                        // The rest of the files will be copied
                    ]
                }
                {
                    "path": "/data/photos"
                    // If no file rules, all directory will be copied,
                    // which is equivalent to:
                    // "file_rules": [
                    //     {
                    //         "regex": ".*",
                    //         "command": "copy"
                    //     }
                    // ]
                }
            ],
            // Rclone remote name in Rclone configuration (the name in [])
            "rclone_remote": "default",
            // Remote path (e.g. bucket name)
            "remote_path": "my_bucket/prefix",
            // The backup schedule
            "schedule": {
                // There are two options to schedule
                // 1. Specifying time HH:MM for every day
                "daily": [
                    "01:00",
                    "12:00",
                    "22:00" // 10:00pm
                ],
                // 2. Specify an interval which can be string like "30m", "1h", "300s", etc.
                "every": "30m" // backup every 30 minutes
            }
        }
        // More backup rules can be specified
    ]
}

Note that comments are not supported in JSON file. They are used to explain the fields here.

The program can be exited using Ctrl-C. If you need to backup sqlite files, please make sure sqlite3 command line is in your PATH.

In Docker

The backpack container can be used to backing up files from other container by sharing their volume path. For example, if you want to back up your vaultwarden password manager's vault files, you can use the following Docker compose file:

version: '3'
services:
  vaultwarden:
    image: 'vaultwarden/server:latest'
    restart: unless-stopped
    volumes:
      - ${HOME}/vaultwarden:/data

  backpack:
    image: 'easyselfhost/backpack:latest'
    restart: unless-stopeed
    volumes:
      # Backpack config file
      - ${HOME}/backpack/config.json:/config/config.json
      # Rclone config file
      - ${HOME}/backpack/rclone.conf:/config/rclone.conf
      - ${HOME}/vaultwarden:/data/vaultwarden

Documentation

Index

• Constants
• func GetExecPath(name string) string
• func SnapshotDir(rule DirRule, dest string) error
• func UploadDir(rule BackupRule, dir string) error
• type BackpackFlow
  • func (bf *BackpackFlow) Run() (err error)
• type BackupRule
• type Config
  • func ParseConfigFromBytes(data []byte) (Config, error)
  • func ParseConfigFromFile(path string) (Config, error)
• type Cron
  • func NewCron() *Cron
  • func NewCronFromConfig(config *Config) (*Cron, error)
  • func NewCronWithScheduler(scheduler *gocron.Scheduler) *Cron
  • func (c *Cron) RegisterDaily(name string, wf Workflow, daily []string) error
  • func (c *Cron) RegisterInterval(name string, wf Workflow, every string) error
  • func (c *Cron) StartAsync()
  • func (c *Cron) Stop()
• type DirRule
• type FileCommand
• type FileRule
  • func (fr *FileRule) UnmarshalJSON(data []byte) error
• type RetryingWorkflow
  • func (wf *RetryingWorkflow) Run() error
• type Schedule
• type Workflow
  • func NewBackpackFlow(uploadRule BackupRule) Workflow
  • func NewRetryingWorkflow(workflow Workflow, retries uint) Workflow

Constants

const Version = "0.1"

Functions

func GetExecPath

func GetExecPath(name string) string

func SnapshotDir

func SnapshotDir(rule DirRule, dest string) error

func UploadDir

func UploadDir(rule BackupRule, dir string) error

Types

type BackpackFlow

type BackpackFlow struct {
	// contains filtered or unexported fields
}

func (*BackpackFlow) Run

func (bf *BackpackFlow) Run() (err error)

type BackupRule

type BackupRule struct {
	Directories  []DirRule `json:"directories"`
	RcloneConfig string    `json:"rclone_remote"`
	RemotePath   string    `json:"remote_path"`
	Schedule     Schedule  `json:"schedule"`
}

type Config

type Config struct {
	Version     string       `json:"version"`
	BackupRules []BackupRule `json:"backups"`
}

func ParseConfigFromBytes

func ParseConfigFromBytes(data []byte) (Config, error)

func ParseConfigFromFile

func ParseConfigFromFile(path string) (Config, error)

type Cron

type Cron struct {
	// contains filtered or unexported fields
}

func NewCron

func NewCron() *Cron

func NewCronFromConfig

func NewCronFromConfig(config *Config) (*Cron, error)

func NewCronWithScheduler

func NewCronWithScheduler(scheduler *gocron.Scheduler) *Cron

func (*Cron) RegisterDaily

func (c *Cron) RegisterDaily(name string, wf Workflow, daily []string) error

func (*Cron) RegisterInterval

func (c *Cron) RegisterInterval(name string, wf Workflow, every string) error

func (*Cron) StartAsync

func (c *Cron) StartAsync()

func (*Cron) Stop

func (c *Cron) Stop()

type DirRule

type DirRule struct {
	SrcDir    string     `json:"path"`
	FileRules []FileRule `json:"file_rules"`
}

type FileCommand

type FileCommand string

const (
	Copy   FileCommand = "copy"
	Sqlite FileCommand = "sqlite"
	Ignore FileCommand = "ignore"
)

type FileRule

type FileRule struct {
	Regex   *regexp.Regexp
	Command FileCommand
}

func (*FileRule) UnmarshalJSON

func (fr *FileRule) UnmarshalJSON(data []byte) error

type RetryingWorkflow

type RetryingWorkflow struct {
	// contains filtered or unexported fields
}

func (*RetryingWorkflow) Run

func (wf *RetryingWorkflow) Run() error

type Schedule

type Schedule struct {
	DailySchedule []string `json:"daily"`
	EveryInterval string   `json:"every"`
}

type Workflow

type Workflow interface {
	Run() error
}

func NewBackpackFlow

func NewBackpackFlow(uploadRule BackupRule) Workflow

func NewRetryingWorkflow

func NewRetryingWorkflow(workflow Workflow, retries uint) Workflow