BorgUI is a laravel powered application that sits on top of BorgBackup. BorgBackup itself does not come with an own UI but a powerful CLI. To fill this gap and to be able to view backups from anywhere I started writing a UI.

I am still missing a lot of features like initialize a repository, trigger a backup, or delete old backups. This is because I set up BorgBackup as described in the official documentation and do the maintenance of my backups through a systemd timer before I started implementing a UI for it.

In regard to BorgUI the above means that you can attach it to an existing BorgBackup Repository, browse the existing backups, and download files or folders from any of them.

In my setup I use the following:

Please have these available before you proceed with installing BorgUI.

Either use the package manager of your OS or execute the following command which will install it in the version defined in the borg.php config file inside the ./config folder.

# cd into root folder of BorgUI
cd /path/where/you/extracted/the/archive

# install BorgBackup in the specified version 
pip install borgbackup==$(php -r "echo (require('./config/borg.php'))['version'];")

BorgUI requires a valid MySQL database and user created before you can proceed with the installation. Please see the following as a reference and make sure you replace the values with something that fits your needs.

# please replace 'borg' and 'secret' with appropriate values
CREATE DATABASE IF NOT EXISTS `borg`;
CREATE USER IF NOT EXISTS 'borg'@'%' IDENTIFIED BY PASSWORD 'secret';
GRANT USAGE ON *.* TO 'borg'@'%';
GRANT ALL PRIVILEGES ON `borg`.* TO 'borg'@'%';

To execute tasks or jobs in the background BorgUI uses Laravel Horizon. All the details are in the deployment section of Horizon.

An example supervisor program configuration may look like:

[program:horizon]
process_name=%(program_name)s
command=php <full path to the installation of borgui>/artisan horizon
autostart=true
autorestart=true
user=<web server user>
redirect_stderr=true
stdout_logfile=<full path to the installation of borgui>/storage/logs/horizon.log
stopwaitsecs=3600

To install BorgUI please download a version from the release page, extract the archive, and run composer to install the dependencies. It is advisable to unzip the archive and execute the commands as the user of your web server.

# cd into root folder of BorgUI
cd /path/where/you/extracted/the/archive

# check if you match the platform requirements
composer check-platform-reqs --no-dev

# install dependencies
composer install --classmap-authoritative --no-dev

# publish horizon assets
artisan horizon:publish

# migrate database changes
artisan migrate --step

# cache configs, routes, and views for performance
artisan config:cache
artisan route:cache
artisan view:cache

# install dependencies for compiling the view assets
yarn install --ignore-optional

# compile view assets
npm run production

Please also consult the official Laravel documentation about deploying Laravel to a server.

All configuration settings can and should be done through environment variables. You may either put them into your global environment file or, what is recommended, create a .env in the root of the installation. I'll only explain the values that are required to run the application. Please refer to the .env.example file as a reference for all the possible environment variables. If you need to set any other environment variable, which is not explained in the list below, please refer to the Laravel Documentation for detailed explanation.

As a general advise you should only publish the environment variables which are necessary.

With every release I also release a docker image on hub.docker.com which I use in my production environment in a swarm cluster. The image includes all direct application requirements like BorgBackup, Nginx, PHP, and supervisor. All assets have been compiled already and are included as well.

Still, you need to provide a MySQL database and a Redis server and configure the application (see above).

If you are using a Docker Swarm Cluster, or alike, my Ansible role for BorgUI and my Ansible playbook, I make use of to roll out the Docker image to production, are maybe interesting for you as well.

Thank you for considering contributing to BorgUI! A PR is always very welcome. If you can't implement a bug fix or behavior change on your own you may write an issue explaining the current behavior and the expected change. Please also describe what problem would be solved after implementing the change.

I added my Homestead configuration for your convenience. Please check Homestead.yaml before you run vagrant up to prevent any IP conflicts in your existing network. I also recommend reading the official documentation of Homestead.

If you discover a security vulnerability within BorgUI, please send an e-mail to Volker Machon via github@olafnorge.de. All security vulnerabilities will be promptly addressed.

BorgUI is open-source software licensed under the MIT license.