= Micromata BorgBackup-Butler
Micromata GmbH, Kai Reinhard
:toc:
:toclevels: 4

Copyright (C) 2018-2021

ifdef::env-github,env-browser[:outfilesuffix: .adoc]

== Why?

* Accessing your borg backups in an very convenient and fast way.
* Caches remote repo archive information for fast browsing.
* Differ functionality to see the differences of backups (files, directories etc.)

== At first glance

After starting BorgButler without any further settings, you can play with faked demo repositories.

[#img-configuration]
You may leave the default values as they are. BorgButler downloads the current or configured version of the borg binary for
your platform automatically.
[link=doc/images/screen-configuration.png]
image::doc/images/screen-configuration.png[Configuration of BorgButler,800]

[#img-jobmonitor]
The job monitor gives an overview of all (long running) processes. You're also able to cancel running jobs.
[link=doc/images/screen-jobmonitor.png]
image::doc/images/screen-jobmonitor.png[Job monitor,800]

[#img-repositories]
Borgbutler may manage multiple repositories.
[link=doc/images/screen-repositories.png]
image::doc/images/screen-repositories.png[Multiple repositories,800]

[#img-repository-config]
Configuration of a repo used by BorgButler.
[link=doc/images/screen-repository-config.png]
image::doc/images/screen-repository-config.png[Configuration of a repo,800]

[#img-repository-archives]
Overview of available archives in your BorgBackup repo.
[link=doc/images/screen-repository-archives.png]
image::doc/images/screen-repository-archives.png[Archives of a repo,800]

[#img-archive-filelist]
The content of an archive (browseable as tree, searchable). You are also able to compare to archives and see the difference
with a view clicks. You may download single files as well as whole directories.
[link=doc/images/screen-archive-filelist.png]
image::doc/images/screen-archive-filelist.png[Repo info,800]

[#img-archive-differences]
You may compare two archives within some clicks and see the differences (files, file properties such as size, dates or change modes).
[link=doc/images/screen-archive-differences.png]
image::doc/images/screen-archive-differences.png[Repo info,800]

== Quick start
=== Docker

BorgButler working directory `$HOME/BorgButler` is assumed, but you may define any other.

1. Create your local BorgButler directory: `mkdir $HOME/BorgButler` (for config, caches, backups and restoring of backuped files and directories)
2. `docker run -v $HOME/BorgButler:/BorgButler -v  $HOME/.ssh:/home/borgbutler/.ssh:ro -p 127.0.0.1:9042:9042 --name borgbutler kreinhard/borgbutler` (exporting of `.ssh` is useful for ssh remotes, otherwise skip this setting.)
3. Stopping: simly click `CTRL-C`.
4. Restart: `docker start`
5. Stop: `docker stop`

Enjoy BorgButler by opening your browser: http://localhost:9042

You may refer the log file through the web browser or in `$HOME/BorgButler/borgbutler.log`.

=== Starting from Java zip
You'll need OpenJDK 9+.

1. Download BorgButler from https://sourceforge.net/projects/borgbutler/files/latest/download
2. Unzip `borgbutler-server/build/distributions/borgbutler-server-<version>.zip`
3. Run `bin/borgbutler-server` or `bin/borgbutler-server.bat`.

=== Starting from sources
You'll need OpenJDK 9+ as well as gradle.

1. `gradle clean distZip`
2. Unzip `borgbutler-server/build/distributions/borgbutler-server-<version>.zip`
3. Run `bin/borgbutler-server` or `bin/borgbutler-server.bat`.

Enjoy BorgButler by opening your browser: http://localhost:9042

== Further information

=== Configuration
=== Example config file
You can configure it through the webapp or directly (`borgbutler.config`):

[source,yaml]
----
borgCommand: "/Users/kai/.borgbutler/bin/borg-macosx64-1.1.8"
maxArchiveContentCacheCapacityMb: 200
repoConfigs:
- displayName: "ACME - Backup server 1"
  repo: "ssh://backupserver.acme.com:23/./backups/backup-server1"
  rsh: "ssh -i /BorgButler/.ssh/acme_rsa"
  passwordCommand: "security find-generic-password -a $USER -s borg-passphrase -w"
  id: "8af6c559b07d598af6c559b07d598af6c559b07d598af6c559b07d598af6c559"
- displayName: "ACME - Backup server 2"
  repo: "ssh://backupserver.acme.com:23/./backups/backup-server2"
  rsh: "ssh -i /BorgButler/.ssh/acme_rsa"
  passwordCommand: "security find-generic-password -a $USER -s borg-passphrase -w"
  id: "ae00099254dc44ae00099254dc44ae00099254dc44ae00099254dc44ae000992"
- displayName: "Debian - Backup server 1"
  repo: "ssh://kai@debian.acme.priv/opt/borg-backups/backup-server1"
  rsh: ""
  passwordCommand: "security find-generic-password -a $USER -s borg-passphrase -w"
  id: "not_yet_loaded_1"
port: 9042
showDemoRepos: false
----

== Example on how to script backups (Linux/MacOS)
Here: link:doc/ExampleBorgConfig{outfilesuffix}[Installation]


==== Backups of configuration files

You may configure and initialize your repositories by the BorgButler app. The config file is generated by BorgButler. Before
saving a new configuration BorgButler stores a copy of the current configuration in the backup dir: `~/.borgbutler/backup/`.


== More immpressions

See some more screens to get an first overview of the functionality of BorgButler.

[#img-repository-info]
Information about your repo.
[link=doc/images/screen-repository-info.png]
image::doc/images/screen-repository-info.png[Repo info,800]

[#img-logviewer]
There is a log file available as well as an log viewer including search functionality.
[link=doc/images/screen-logviewer.png]
image::doc/images/screen-logviewer.png[Log viewer of BorgButler,800]