Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vesparny/borgjs
📦 A tiny wrapper for BorgBackup to automate your backup workflow
https://github.com/vesparny/borgjs
attic backup borg borgbackup nodejs
Last synced: 12 days ago
JSON representation
📦 A tiny wrapper for BorgBackup to automate your backup workflow
- Host: GitHub
- URL: https://github.com/vesparny/borgjs
- Owner: vesparny
- License: mit
- Created: 2016-05-26T16:48:14.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2018-01-19T10:44:54.000Z (almost 7 years ago)
- Last Synced: 2024-11-01T13:51:44.737Z (19 days ago)
- Topics: attic, backup, borg, borgbackup, nodejs
- Language: JavaScript
- Homepage:
- Size: 120 KB
- Stars: 30
- Watchers: 6
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# 📦 borgjs
> A tiny wrapper for BorgBackup to automate your backup workflow
[](https://gitter.im/borgjs/discussion)
[](https://www.npmjs.com/package/borgjs)
[](https://travis-ci.org/vesparny/borgjs)
[](https://npm-stat.com/charts.html?package=borgjs&from=2016-10-17)
[](https://david-dm.org/vesparny/borgjs)
[](http://standardjs.com/)
## Overview
**Please note borgjs needs you to run node >=6 and has been tested using borg**
* v1.0.7
* v1.0.8
* v1.0.9
* v1.0.10
* v1.1.4
borgjs is a nodejs command line tool for [BorgBackup](http://borgbackup.readthedocs.io/en/stable/).
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, de-duplication and 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](#configuration), run borgjs in a crontab and forget about it.
It will take care of your backup workflow, sending you status reports through different possible channels.
## Features
* backup creation
* prune old backup according to a set of rules declared in the [configuration file](#configuration).
* check backups for consistency and integrity.
* `onFinish` hook to do anything you want after finishing a backup.
* lockfile system to prevent concurrent backup process running in the same destination.
* output borg messages to stdout for easy logging.
* highly [configurable](#configuration).
* allow to fully customize borg commands and environment variables.
## Usage CLI
In order to use borgjs, you need to configure borg before.
This is an easy step, just follow the [installation](http://borgbackup.readthedocs.io/en/stable/installation.html) guide on the borg website.
Initialize an empty borg repository (for more details see the borg [quickstart](http://borgbackup.readthedocs.io/en/stable/quickstart.html) guide)
```
$ borg init /path/to/repo
```
Install borgjs globally
```
$ npm i -g borgjs
```
Running a backup is as easy as creating a [borg repository](http://borgbackup.readthedocs.io/en/stable/usage.html#borg-init) and run
```shell
$ borgjs -c /User/me/borgjs.config.js
```
or
```
$ borgjs $(date +%Y-%m-%d-%H%M%S) -c /User/me/borgjs.config.js >> /Users/me/logs/$(date +%Y-%m-%d-%H%M%S).log
```
in case you want to specify the archive name and log to a file (useful if you run in as a cronjob).
```
$ borgjs --help
A tiny wrapper for BorgBackup to automate your backup workflow
Usage
$ borgjs
Options
-c, --config config file path
Examples
# run borgjs
$ borgjs -c=/User/me/borgjs.config.js
#run borgjs specifying the archive name, and log output to a file
$ borgjs $(date +%Y-%m-%d-%H%M%S) -c /path/to/your/borgjs.config.js >> $(date +%Y-%m-%d-%H%M%S).log
```
## Usage API
You can also use borgjs programmatically:
```js
const borgjs = require('borgjs')
const config = {
repository: '/Users/arny/Desktop/test/',
paths: [
'/Volumes/External/'
]
}
const archiveName = new Date().toString()
borgjs(config, archiveName)
.then(() => console.log('success'))
.catch((err) => console.log('error', err))
```
## `onFinish` hook
By defining an `onFinish` callback function in the configuration file, it's possible to run any arbitrary code when a backup finishes.
```js
// the config file
module.exports = {
onFinish: function (err, data, done) {
if (err) {
console.log('An error happened', err)
} else {
console.log(`Archive ${data.archiveName} created.`)
}
// invoke the done callback to let the process terminate properly
done()
}
}
```
It's possible to use the `onFinish` callback to send emails or notifications about the executed backup (see the paragraph below for an example)
## Configuration
```js
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 '[email protected]: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
],
// An array of files/directories to exclude from backup
// exclude: [
// '*/node_modules',
// '*.DS_Store'
// ],
// A prefix for backup archives
// archivePrefix: 'backup-',
// Create backup archive
// Use the options array to pass any options supported by borg create
// See https://borgbackup.readthedocs.org/en/stable/usage.html#borg-create
create: {
options: [
'--compression', 'lz4',
'--filter', 'AME?'
]
},
// Check repo consistency
// Use the options array to pass any options supported by borg check
// See https://borgbackup.readthedocs.org/en/stable/usage.html#borg-check
// check: {
// options: []
// },
// Retention policy for pruning old backups
// Use the options array to pass any options supported by borg prune
// https://borgbackup.readthedocs.org/en/stable/usage.html#borg-prune for details.
// prune: {
// options: [
// '-d', 30,
// '-w', 30,
// '--keep-within', '31d'
// ]
// }
// Set the following environment variables
// See https://borgbackup.readthedocs.io/en/stable/usage.html#environment-variables
env: {
BORG_REMOTE_PATH: 'borg1',
BORG_PASSPHRASE: 'passphrase'
},
// the onFinish callback
onFinish: function (err, data, done) {
const message = err
? 'the backup failed'
: `the archive ${data.archiveName} has been created`
var execSync = require('child_process').execSync
const command = `
curl -s --user 'api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0' \
https://api.mailgun.net/v3/samples.mailgun.org/messages \
-F from='Excited User ' \
-F to='[email protected]' \
-F subject='Hello from borgjs' \
-F text='${message}'
`
try {
execSync(command)
} catch (e) {}
// invoke the done callback to let the process terminate properly
done()
}
}
```
## Automate
A backup is not a backup if it's not automated.
I personally use [cronnix](https://www.macupdate.com/app/mac/7486/cronnix) to schedule my backup sessions on my mac.
## 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](http://rclone.org/)
* I personally use [rsync.net](http://rsync.net/) for my backup, they also apply [dirt cheap](http://www.rsync.net/products/attic.html) pricing model to borg users.
Please note I'm not affiliated with them, I'm just an happy paying customer.
## Change Log
This project adheres to [Semantic Versioning](http://semver.org/).
Every release, along with the migration instructions, is documented in the [CHANGELOG.md](https://github.com/vesparny/borgjs/blob/master/CHANGELOG.md) file.
## License
MIT