borgjs

📦 borgjs

A tiny wrapper for BorgBackup to automate your backup workflow

Overview

Please note borgjs needs you to run node >=4 and has been tested using borg v1.0.7

borgjs is a nodejs command line tool for BorgBackup.

After having tried a lot of backup solutions for my data, I've been using Borg for quite a while. It's rock solid and never let me down. It supports compression and authenticated encryption.

Backups should be as boring as possible, that's why I've created this tool in order to automate and constantly monitor the whole process, making it a little bit more user friendly.

Instead of writing complex bash scripts you can now just write a declarative configuration file, run borgjs in a crontab and forget about it.

It will take care of your backup workflow, sending you reports and writing detailed log files.

Also the console output looks pretty good.

Features

• backup creation
• prune old backup according to a set of rules declared in the configuration file.
• check backups for consistency and integrity
• send success/failure reports via email, push notifications on your phone or native OS notifications
• lockfile system based on PID in order to avoid concurrent backups to the same destination
• logs to a different file details about the backup session such as borg output and commands executed
• highly configurable

Notifications

borgjs supports a wide range of notifications, besides detailed logs creation.

This enables you to always keep an eye on your backups.

Notifications will never contain sensitive informations such as encryption keys of files involved in the backup process. They will just contain the path of the generated log file and the status (success/error).

• OS native notifications

• push notifications (via pushbullet)

• email notifications

Configuration

module.exports = {
  // Specify an alternative absolute path for the borg executable
  // defaults to the one in $PATH
  // borgPath: '',

  // Borg repository path
  // can be remote or local
  // see http://borgbackup.readthedocs.io/en/stable/usage.html#borg-init
  // e.g. '/Users/me/Desktop/borg_backup' or '[e-mail]:borg_backup'
  repository: '', // MANDATORY

  // An array of absolute paths to include in the backup
  // paths that do not exist will be excluded (useful when a network share is not mounted)
  paths: [ // MANDATORY
    //  '/Users/me',
    //  '/etc
  ],

  // The logs dir absolute path
  // defaults to ~/.borgjs/logs
  // logsDir: '',

  // An array of files/directories to exclude from backup
  // exclude: [
  //  '*/node_modules',
  //  '*.DS_Store'
  // ],

  // A prefix for backup archives
  // archivePrefix: 'backup',

  // Type of compression to use when creating archives.
  // See https://borgbackup.readthedocs.org/en/stable/usage.html#borg-create
  // lz4, zlib, lzma
  compression: '',

  // The encryption passphrase that will be used to set BORG_PASSPHRASE env variable
  // necessary to run automated backups with borg if your repository has been created with encryption
  //  passphrase: '',

  // Check repo consistency
  // See https://borgbackup.readthedocs.org/en/stable/usage.html#borg-check
  check: true,

  // Retention policy for pruning old backups
  // https://borgbackup.readthedocs.org/en/stable/usage.html#borg-prune for details.
  // prune: {
  //    H: 10,
  //    d: 7,
  //    w: 4,
  //    m: 6,
  //    y: 1,
  //    'keep-within': '31d'
  // },

  // Email configuration
  // See https://github.com/nodemailer/nodemailer options
  //  email: {
  //    from: '[e-mail]',
  //    to: '[e-mail]',
  //    smtpHost: 'smtp.mailgun.org',
  //    smtpPort: 587,
  //    user: '[e-mail]',
  //    pass: 'mypass',
  //    secure: false
  //  },

  // Send an email on success (the 'email' section must be configured)
  // sendSuccessMail: true,

  // Send an email on error (the 'email' section must be configured)
  // sendErrorMail: true,

  // Send native Desktop notifications on success/error
  sendSystemNotification: true

  // Send push notifications on success/error to your devices connected to pushbullet
  // See https://www.pushbullet.com/
  // pushbullet: {
  //  accessToken: 'your pushbullet access token'
  // }
}

CLI Usage

Running a backup is as easy as creating a borg repository and run

$ borgjs --config=/User/me/borgjs.config.js

$ borgjs --help

  📦  A tiny wrapper for BorgBackup to automate your backup workflow

  Usage
    $ borgjs <options>

  Options
    -c, --config          path of a borgjs config file.

  Examples
    borgjs --config=/User/me/borgjs.config.js

Automate

A backup is not a backup if it's not automated.

I personally use cronnix to schedule my backup sessions on my mac.

I also run it on a headless Raspberry Pi.

Recipes

• Borg can store data on any remote host accessible over SSH. If you prefer to store your offsite backup in some other fancy cloud storage, you can always backup to a local target, then upload it anywhere using rclone

• I personally use rsync.net for my backup, they also apply dirty cheap pricing model to borg users. Please not I'm not affiliated with them, I'm just an happy paying customer.

Change Log

This project adheres to Semantic Versioning.
Every release, along with the migration instructions, is documented in the CHANGELOG.md file.

License

MIT

Changelog

1.0.0 (2016-10-20)

Bug Fixes

• lib: Remove check for borg in path (b1e8f49)

Features

• lib: Initial commit (f4cad37)
• notifications: Add pushbullet support (921c316)