|
| 1 | +# backmeup - a lightweight backup utility for the CLI |
| 2 | +When managing several servers, you often come across ... I searched for backup tools online but never found an easy-to-use, leightweight, portable, CLI tool which is easy to configure and does not need a remote server for backups. |
| 3 | +That's why I created backmeup. |
| 4 | + |
| 5 | +### Key features |
| 6 | +- Easy to use |
| 7 | +- Define multiple backups in a single config file |
| 8 | +- **Portable** - you can copy the **single executable** with a configuration file on all your machines |
| 9 | +- **Lightweight** - the executables are ~1 mb |
| 10 | +- Exclude files and paths with .gitignore-like syntax |
| 11 | +- Group together multiple source paths into one backup |
| 12 | +- Config files written in yaml |
| 13 | +- Usable from the CLI |
| 14 | +- Multi-platform support |
| 15 | + |
| 16 | +# Installation |
| 17 | + |
| 18 | +## Download precompiled executable |
| 19 | +Under the releases page you'll always find the most recent builds of backmeup as executables for linux, windows and macos (amd64). |
| 20 | +These executables are built with `go build -ldflags="-s -w" .` shrinked with [upx](https://github.com/upx/upx/). |
| 21 | + |
| 22 | +In case that's not suitable for you, you can always build the executable from source. |
| 23 | + |
| 24 | +## Compile from source |
| 25 | +This tool is written in Go (golang), so you need to have Go installed on your system first. You can find [installation instructions here](https://golang.org/doc/install). |
| 26 | + |
| 27 | +Then you need to clone the git repository. |
| 28 | +Afterwards select the operating system you want to compile for, and the corresponding architecture (Go allows for easy cross compilation) from [this](https://gist.github.com/asukakenji/f15ba7e588ac42795f421b48b8aede63) list. |
| 29 | +Set the environment variables `GOOS` and `GOARCH` with those values and eventually use `go build .` to generate an executable. |
| 30 | +```bash |
| 31 | +$ git clone https://github.com/d-Rickyy-b/backmeup |
| 32 | +$ cd backmeup |
| 33 | +$ GOOS="linux" && GOARCH="amd64" |
| 34 | +$ go build -ldflags="-s -w" . |
| 35 | +``` |
| 36 | +After that you have an executable named `backmeup` in your current working directory. |
| 37 | + |
| 38 | +## Making it persistent |
| 39 | +While backmeup is meant to be portable and can be executed from everywhere, you might want to permanently install it on your system. |
| 40 | +On linux you can simply move the file into the `/bin/` directory. |
| 41 | +```bash |
| 42 | +$ mv backmeup /bin/backmeup |
| 43 | +``` |
| 44 | + |
| 45 | +On Windows, you can create a new directory in the `Program Files` directory and move the binary there. |
| 46 | +``` |
| 47 | +> mkdir C:\Program Files\backmeup\ |
| 48 | +> mv backmeup.exe C:\Program Files\backmeup\backmeup.exe |
| 49 | +``` |
| 50 | + |
| 51 | +# Usage |
| 52 | +All you need for this tool to work is a `config.yml` file. Simply pass the path to that file via the `-c`/`--config` switch. |
| 53 | +``` |
| 54 | +usage: backmeup [-h|--help] -c|--config "<value>" [-v|--verbose] |
| 55 | +
|
| 56 | + The lightweight backup tool for the CLI |
| 57 | +
|
| 58 | +Arguments: |
| 59 | +
|
| 60 | + -h --help Print help information |
| 61 | + -c --config Path to the config.yml file |
| 62 | + -v --verbose Enable verbose logging. Default: false |
| 63 | +``` |
| 64 | + |
| 65 | +Starting your backups is as simple as this |
| 66 | +``` |
| 67 | +$ backmeup -c config.yml |
| 68 | +``` |
| 69 | + |
| 70 | +# How to create a config? |
| 71 | +Configuring your backups is easy. Just create a `config.yml` file that contains the information about the sources and destination paths for your backups. |
| 72 | + |
| 73 | +```yaml |
| 74 | +backup_unit_name: |
| 75 | + sources: |
| 76 | + - C:\Users\admin\Documents\ |
| 77 | + - 'C:\Users\admin\Dropbox' |
| 78 | + - "C:\\Users\\admin\\AppData\\Roaming\\.minecraft" |
| 79 | + destination: 'C:\backups' |
| 80 | + excludes: |
| 81 | + - "*.zip" |
| 82 | + - "*.rar" |
| 83 | + archive_type: "tar.gz" |
| 84 | + add_subfolder: false |
| 85 | + enabled: true |
| 86 | +``` |
| 87 | +The minimal configuration consists only of the unit's name (obviously), at least one source and the destination path: |
| 88 | +
|
| 89 | +```yaml |
| 90 | +backup_unit_name: |
| 91 | + sources: |
| 92 | + - C:\Users\admin\Documents\ |
| 93 | + destination: 'C:\backups' |
| 94 | +``` |
| 95 | +
|
| 96 | +The name of your backup is the key at root level. Starting from there you can configure the following parameters. |
| 97 | +
|
| 98 | +| Parameter | Type | Required | Default | Description | |
| 99 | +|---|---|---|---|---| |
| 100 | +| sources | list[strings] | Yes | | All paths to the directories you want to include in your backup | |
| 101 | +| destination | string | Yes | | The destination directory, where the backup of this unit will be stored at | |
| 102 | +| excludes | list[strings] | No | `[]` | .gitignore like filters for excluding files or dirs from the backup | |
| 103 | +| archive_type | string | No | `tar.gz` | The type of archive to be used (`tar.gz` or `zip` are valid options) | |
| 104 | +| add_subfolder | boolean | No | `false` | Creates a new subfolder in <destination> for this unit if set to true | |
| 105 | +| enabled | boolean | No | `true` | Switch to disable each unit individually | |
| 106 | + |
| 107 | +Take care when using quotes in paths. For most strings you don't even need to use quotes at all. When using double quotes (`"`), you must escape backslashes (`\`) when you want to use them as literal characters (such as in Windows paths). |
| 108 | +Check [this handy article](https://www.yaml.info/learn/quote.html) for learning more about quotes in yaml. |
0 commit comments