= 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 `${BorgButlerHome}/borgbutler.log`.

For new versions of BorgButler or for changing the running options of your BorgButler container, simply delete the BorgButler docker container by `docker rm borgbutler` and call `docker run` again.

=== 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`.

As BorgButler default home directory, `${HOME}/.borgbutler` is used.

=== 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: "${BorgButlerHome}/bin/borg-macosx64-1.1.9"
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: `${BorgButlerHome}/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]


== Trouble shooting
=== Docker
==== Increase memory (OutOfMemory)
Edit `${BorgButlerHome}/environment.sh` and restart your docker container (since version 0.6).

[source,bash]
----
#!/bin/bash

export JAVA_OPTS=-DXmx4g
----

If your docker container crashes on heavy usage of large borg archives, check the memory settings of your docker installation.

=== How to download/restore?
You may restore files or while directories by simply clicking the download icon. If you run BorgButler on localhost as Java process (not docker), after restoring single
files or directories your system's file browser is opened.

You will find all the restored files in the `restore` subdirectory of your BorgButler home directory.

=== Access to Borg repo fails (lock)
BorgButler tries to run only one job per repo at the same time. If your log file shows error on `Failed to create/acquire the lock ... lock.exclusive (timeout)` simply restart BorgButler.


=== Browsing produces security warnings
Due to security reasons, BorgButler is only available by the localhost's web browser. For docker
installations the clients of the private net `172.17.0.*` are allowed.
For enabling other client ip's, you may use option `-DallowedClientIps=192.168.78.` (docker: `docker run -e JAVA_OPTS="-DallowedClientIps=192.168.78.;192.168.79.5" -v ...` if your really now what you're doing!!! There is now https available at default!!!
