butterfly_backup_web documentation¶
Presentation¶
Butterfly Backup is a modern backup program that can back up your files. It is a command line tool.
butterfly_backup_web is a web interface of the Butterfly Backup command line tool.
Installation¶
A simple installation is done directly from the repository.
git clone https://github.com/MatteoGuadrini/butterfly-backup-web.git
cd butterfly-backup-web
pip install . --upgrade
Docker¶
Butterfly Backup Web is distribuited with containerization files. You can build the image:
cd butterfly-backup-web
docker build . -t bbweb:latest
docker run -d -v /backup_catalog/:/tmp/backup/ -p 8080:8080 -e DJANGO_SUPERUSER_PASSWORD="MyComplexPassword0!" -e BB_CATALOG_PATH="/backup" localhost/bbweb:latest
If you want preserve the data, create a volume and map to container:
# Create a volume
docker volume create bbweb
# Run container
docker run -d -v bbweb:/tmp/backup/ -p 8080:8080 localhost/bbweb:0.1.0
Customize Docker image¶
Docker image born with enviroment variables; modifying these variables to customized experience:
vim Dockerfile
...
DJANGO_SUPERUSER_PASSWORD="Admin000!"
DJANGO_SUPERUSER_USERNAME="admin"
DJANGO_SUPERUSER_EMAIL="admin@bbweb.com"
BB_CATALOG_PATH="/tmp/backup"
...
Environment variables¶
The following environment variables are available for Butterfly Backup Web:
Variable |
Description |
Default |
|---|---|---|
BB_CATALOG_PATH |
Backup catalog directory. |
/tmp/backup |
DJANGO_SUPERUSER_USERNAME |
Default admin username for the initial Docker image. |
admin |
DJANGO_SUPERUSER_PASSWORD |
Default admin password for the initial Docker image. |
Admin000! |
DJANGO_SUPERUSER_EMAIL |
Default admin email for the initial Docker image. |
|
BBWEB_SSL_ENABLE |
Enable HTTPS and secure cookie/HSTS settings. |
False |
BBWEB_SSL_CERTIFICATE_PATH |
Path to the SSL certificate file used by the custom runserver command. |
(none) |
BBWEB_SSL_KEY_PATH |
Path to the SSL private key file used by the custom runserver command. |
(none) |
BBWEB_SSL_CA_CERTIFICATE_PATH |
Optional path to a CA bundle for HTTPS. |
(none) |
BBWEB_SECURE_HSTS_SECONDS |
The HSTS max-age value in seconds when SSL is enabled. |
31536000 |
BBWEB_SECURE_HSTS_INCLUDE_SUBDOMAINS |
Enable HSTS for subdomains when SSL is enabled. |
True |
BBWEB_SECURE_HSTS_PRELOAD |
Enable HSTS preload when SSL is enabled. |
True |
Configuration¶
To configure Butterfly Backup Web, edit your profile and insert your catalog backup:
nano ~/.bashrc # or .zshrc if you use zsh
...
export BB_CATALOG_PATH=/tmp/backup
...
After this, import and create a database:
source ~/.bashrc # or .zshrc if you use zsh
# Use bbweb command line
bbweb migrate
bbweb createsuperuser
bbweb runserver 0.0.0.0:80
# Use Python package
python3 -m butterfly_backup_web migrate
python3 -m butterfly_backup_web createsuperuser
python3 -m butterfly_backup_web runserver 0.0.0.0:80
# Optional HTTPS
bbweb runserver --ssl 0.0.0.0:8443 --cert /path/to/server.crt --key /path/to/server.key
# or use environment variables
export BBWEB_SSL_ENABLE=1
export BBWEB_SSL_CERTIFICATE_PATH=/path/to/server.crt
export BBWEB_SSL_KEY_PATH=/path/to/server.key
bbweb runserver 0.0.0.0:8443 # or 443 if you have permissions
Note
When SSL is enabled, Butterfly Backup Web uses port 443 (standard HTTPS) or 8443 (alternative HTTPS). Port 443 requires elevated privileges, while port 8443 can be used without special permissions.
Systemd Service¶
If you use linux and systemd in your linux environment, you should configure a bbweb service, like this:
sudo wget -O /usr/lib/systemd/system/bbweb.service https://raw.githubusercontent.com/MatteoGuadrini/butterfly-backup-web/refs/heads/main/systemd/bbweb.service
sudo nano /usr/lib/systemd/system/bbweb.service
[Unit]
Description=Butterfly Backup Web
After=multi-user.target
[Service]
Type=simple
Restart=always
ExecStart=/usr/bin/python3 -m butterfly_backup_web runserver 0.0.0.0:80
Environment="BB_CATALOG_PATH=/tmp/backup" # Modify with your catalog path
[Install]
WantedBy=multi-user.target
Now start and enable it:
sudo systemctl daemon-reload
sudo systemctl enable bbweb.service --now
Systemd Service with HTTPS¶
To enable HTTPS in your systemd service, update the service file with SSL environment variables and port:
sudo nano /usr/lib/systemd/system/bbweb.service
[Unit]
Description=Butterfly Backup Web
After=multi-user.target
[Service]
Type=simple
Restart=always
ExecStart=/usr/bin/python3 -m butterfly_backup_web runserver 0.0.0.0:8443
Environment="BB_CATALOG_PATH=/tmp/backup" # Modify with your catalog path
Environment="BBWEB_SSL_ENABLE=1"
Environment="BBWEB_SSL_CERTIFICATE_PATH=/path/to/server.crt"
Environment="BBWEB_SSL_KEY_PATH=/path/to/server.key"
[Install]
WantedBy=multi-user.target
Then reload and restart the service:
sudo systemctl daemon-reload
sudo systemctl restart bbweb.service