Rebuild Runbook

How to stand BackupBloc Control back up on a fresh server — from bare Debian to a fully-licensed, TLS-terminated, admin-UI-serving host at license.backupbloc.com.

account_treeOverview

BackupBloc Control is a single Flask app + SQLite DB + static admin UI, fronted by nginx with Let's Encrypt TLS. It runs as one systemd service (backupbloc-control.service) on port 5100, and nginx terminates HTTPS on 443.

The server has exactly one job: it is the license & update authority that every customer panel phones home to. Customer panels identify themselves by their public outbound IP — no tokens, no keys. If the control server is offline, panels keep working for 12 hours on the last cached validation, then lock down.

What you need before you start

• A fresh Debian 12 (or Ubuntu 22.04/24.04) box with root SSH access.
• The server's public IP (for the DNS A record).
• Control of the license.backupbloc.com DNS record (or whatever hostname you're using).
• A local clone of the backupbloc-control repo on your dev machine.
• If restoring: the licenses.db, users.json, sessions.json, and releases/ directory backups from the old server.

buildRebuild steps

apt-get update -q && apt-get dist-upgrade -yq

dig +short license.backupbloc.com
# should return the new server IP

# On the new server, as root:
apt-get install -yq git
git clone <your-repo-url> /root/backupbloc-control
cd /root/backupbloc-control

scp -r ./backupbloc-control root@<new-ip>:/root/

cd /root/backupbloc-control
bash install-server.sh --hostname license.backupbloc.com

journalctl -u backupbloc-control.service | grep -i "initial admin password"

# From anywhere:
curl -s https://license.backupbloc.com/api/health
# → {"ok":true,"service":"backupbloc-control"}

# Unlicensed IPs always get 403:
curl -s -X POST https://license.backupbloc.com/api/validate \
  -H "Content-Type: application/json" -d "{}"
# → {"valid":false,"reason":"No license for this IP","ip":"..."}

restoreRestoring from a backup

If you're rebuilding because the old server died, run steps 1–4 on the new box (this creates a fresh empty DB), then stop the service, overwrite the data files, and start it again:

systemctl stop backupbloc-control.service

# Restore from wherever you keep the backup (rsync, S3, restic, etc.)
cp /path/to/backup/licenses.db   /etc/backupbloc-control/licenses.db
cp /path/to/backup/users.json    /etc/backupbloc-control/users.json
cp /path/to/backup/sessions.json /etc/backupbloc-control/sessions.json
rsync -a /path/to/backup/releases/ /var/lib/backupbloc-control/releases/

chown -R root:root /etc/backupbloc-control /var/lib/backupbloc-control
chmod 700 /etc/backupbloc-control
chmod 600 /etc/backupbloc-control/*.json /etc/backupbloc-control/licenses.db /etc/backupbloc-control/config.env

systemctl start backupbloc-control.service
systemctl status backupbloc-control.service

settingsDay-2 operations

Redeploying code changes

From your dev machine, with BBC_PASS set:

export BBC_HOST=license.backupbloc.com BBC_PASS=<root password>

python _deploy_api.py     # pushes license-api.py + schema.sql, restarts service
python _deploy_html.py    # pushes admin/index.html

Both scripts use paramiko over SSH. They restart the systemd service automatically when needed.

Logs and debugging

# Live tail
journalctl -u backupbloc-control.service -f

# Last 200 lines
journalctl -u backupbloc-control.service -n 200 --no-pager

# Nginx access/error
tail -f /var/log/nginx/access.log /var/log/nginx/error.log

# Service state
systemctl status backupbloc-control.service

What to back up on this server

The only stateful paths you need to protect:

Everything else — the app code, systemd unit, nginx config, certbot state — is reproduced by re-running the installer.

TLS certificate renewal

Certbot installs a systemd timer that auto-renews. Check it:

systemctl list-timers | grep certbot
certbot certificates

menu_bookReference

File locations (on the control server)

config.env settings

Restart the service after editing: systemctl restart backupbloc-control.service.

Public API endpoints (customer panels call these)

All public endpoints except /api/health are IP-gated: unlicensed IPs receive 403 {valid:false, reason, ip}.

Release signing keys

Release bundles are signed with an ed25519 keypair. The private key stays on your dev laptop and is never uploaded to the control server. The public key ships in the customer panel installer.

# One-time, on your dev laptop:
bash tools/keygen.sh
# private:  ~/.backupbloc/update-signing-key.pem  (keep offline)
# public :  ~/.backupbloc/update-pubkey.pem

# Each release:
bash tools/sign-bundle.sh dist/backupbloc-1.8.0.tar.gz
# prints the base64 signature — paste into Releases → Upload Release

troubleshootTroubleshooting

Service won't start

journalctl -u backupbloc-control.service -n 50 --no-pager

Common causes: syntax error in config.env, missing Python dep (re-run pip3 install --break-system-packages -r /opt/backupbloc-control/api/requirements.txt), permission issue on /etc/backupbloc-control/ (chmod 700 that dir).

Certbot fails with AttributeError: module 'lib' has no attribute 'X509_V_FLAG_NOTIFY_POLICY'

The Debian 12 / pyOpenSSL / cryptography mismatch. The current installer fixes it automatically; if you hit it on an old install:

pip3 install --break-system-packages --upgrade pyopenssl
certbot --nginx -d license.backupbloc.com --redirect --non-interactive --agree-tos --register-unsafely-without-email

Customer panel says "no license for this IP" but a license exists

• Check their current public IP (ask them to visit https://ifconfig.me). ISPs change CGNAT IPs.
• Confirm TRUST_PROXY=1 is in config.env — otherwise Flask sees nginx's 127.0.0.1 instead of the real client IP.
• Look at the last check-in for that customer in the admin UI; it records the IP they came from.

Admin login rejected but you're sure the password is right

Sessions live in /etc/backupbloc-control/sessions.json — if that file is corrupted, delete it (you'll just have to log in fresh). User accounts live in users.json. To reset the admin user entirely: stop the service, delete users.json, start the service — it will seed a new random password and log it.

Locked out of the admin UI entirely

SSH to the server and run:

systemctl stop backupbloc-control.service
rm /etc/backupbloc-control/users.json /etc/backupbloc-control/sessions.json
systemctl start backupbloc-control.service
journalctl -u backupbloc-control.service -n 20 | grep -i "initial admin password"