BBS can be installed two ways:

• Standard Installation — directly on an Ubuntu Server with the automated installer
• Docker Installation — single container with everything included, no OS dependencies

Both methods support local and Remote Storage (SSH) repository storage.

This section walks through installing BBS on a fresh Ubuntu Server.

Before installing BBS, ensure you have:

1. Fresh Ubuntu Server 22.04 LTS or newer

   • Minimal or standard installation
   • At least 2GB RAM, 50GB disk (see System Requirements for detailed requirements)

2. DNS A Record pointing to your server's IP address

   • Example: backups.example.com → 1.2.3.4
   • Required for automatic SSL certificate generation
   • Not required for LAN-only installations (see LAN Installation Notes below)

3. Root or sudo access to the server

4. Ports 22, 80, and 443 open in your firewall

The BBS installer is a single bash script that automates the entire installation process.

For a standard internet-connected installation with automatic SSL:

curl -sSL https://raw.githubusercontent.com/marcpope/borgbackupserver/main/bin/bbs-install | sudo bash

The installer will:

• Detect your server's hostname from DNS
• Install all required software packages
• Configure Apache with SSL via Let's Encrypt
• Set up MySQL
• Create the BBS directory structure
• Configure cron jobs for scheduled backups

If you want to specify a different hostname:

curl -sSL https://raw.githubusercontent.com/marcpope/borgbackupserver/main/bin/bbs-install -o bbs-install
chmod +x bbs-install
sudo ./bbs-install --hostname backups.example.com

For servers on a private network without a public DNS name:

curl -sSL https://raw.githubusercontent.com/marcpope/borgbackupserver/main/bin/bbs-install -o bbs-install
chmod +x bbs-install
sudo ./bbs-install --no-ssl

This skips Let's Encrypt SSL setup. You'll access BBS via HTTP instead of HTTPS.

The bbs-install script performs 10 automated steps:

Installs required packages via apt:

• php8.1 and extensions (pdo_mysql, mbstring, curl, xml, zip, intl, gd, ssh2)
• mysql-server (MySQL 8.0)
• apache2 (with mod_rewrite, mod_ssl)
• borgbackup
• python3 and python3-pip
• memcached
• rclone
• certbot (for SSL certificates)

• Secures MySQL installation
• Creates bbs database (if not exists)
• Configures authentication

• Creates VirtualHost configuration at /etc/apache2/sites-available/bbs.conf
• Enables required Apache modules (rewrite, ssl, headers)
• Configures document root at /var/www/bbs/public

• Configures php.ini settings for BBS
• Sets memory limits, upload sizes, timezone
• Enables required extensions

• Installs Composer globally
• Runs composer install in /var/www/bbs to install PHP dependencies

• Installs latest BorgBackup from repositories
• Verifies installation

• Runs Certbot to obtain Let's Encrypt certificate
• Configures automatic renewal via cron
• Updates Apache to use HTTPS

• Creates SSH wrapper script for BorgBackup
• Configures SSH keys for agent-server communication

• Installs cron job to run /var/www/bbs/scheduler.php every minute
• This drives the backup job queue and scheduled backups

Creates BBS directories:

/var/www/bbs/          # Application root
/var/www/bbs/config/   # Configuration files
/var/bbs/home/         # Borg repository storage (default)
/var/log/bbs/          # Log files

Sets appropriate ownership and permissions.

After the installer completes, access the setup wizard in your web browser:

https://backups.example.com/setup

(Or http://your-server-ip/setup for LAN installations)

The setup wizard guides you through initial configuration:

The wizard verifies:

• PHP version (8.1+)
• Required PHP extensions
• MySQL connectivity
• Directory permissions
• BorgBackup installation

All checks must pass (green checkmarks) before proceeding.

If checks fail:

• Red X indicates a problem
• Hover over the status icon for details
• Most issues indicate the installer didn't complete successfully; try running it again

Click Next to continue.

Enter MySQL connection details:

• Database Host: localhost (default)
• Database Name: bbs (default, created by installer)
• Database Username: root (or a dedicated MySQL user)
• Database Password: Your MySQL password

The wizard will test the connection. If successful, it creates any missing tables.

Troubleshooting:

• If connection fails, verify MySQL is running: sudo systemctl status mysql
• Check credentials: sudo mysql -u root -p
• Ensure the bbs database exists: sudo mysql -e "SHOW DATABASES;"

Click Next to continue.

Create the primary administrator account:

• Name: Your full name
• Email: Your email address (used for login)
• Password: Choose a strong password (min. 8 characters)
• Confirm Password: Re-enter password

This account will have full administrative access to BBS.

Security Note: Enable Two-Factor Authentication after setup for enhanced security.

Click Next to continue.

Configure storage and server settings:

• Repository Storage Path: /var/bbs/home (default)

  • Where BorgBackup repositories will be stored
  • Must be writable by the www-data user
  • Consider a separate partition/volume (see System Requirements#Storage-Configuration-Recommendations)

• Server Hostname: backups.example.com (auto-detected from your DNS/install)

  • Used by agents to connect to the server
  • Must be accessible from all client machines
  • Include https:// prefix (or http:// for LAN installations)

Click Next to continue.

The wizard performs final setup:

1. Imports Database Schema - Creates all required tables from schema.sql
2. Creates Configuration File - Generates /var/www/bbs/config/.env with your settings
3. Generates APP_KEY - Creates a unique encryption key for sessions and data

A progress indicator shows each step. This takes 10-30 seconds.

When complete, you'll see a success message with a button to log in.

Click Go to Login to access BBS.

1. Navigate to your BBS hostname (e.g., https://backups.example.com)
2. Log in with the administrator email and password you created in Step 3
3. You'll see the BBS dashboard (initially empty)

See the Getting Started guide for a quick walkthrough of:

• Adding a client
• Installing the agent
• Creating a repository
• Configuring your first backup plan

Ensure the BBS scheduler is running:

sudo crontab -l | grep scheduler

You should see:

* * * * * php /var/www/bbs/scheduler.php >> /var/log/bbs/scheduler.log 2>&1

This job runs every minute and processes the backup queue.

Monitor installation and initial operation:

sudo tail -f /var/log/bbs/scheduler.log
sudo tail -f /var/log/apache2/error.log

For BBS servers on isolated LANs without public DNS or internet access:

Use the --no-ssl flag:

sudo ./bbs-install --no-ssl

This skips:

• Let's Encrypt SSL certificate generation
• Certbot installation
• HTTPS configuration

Access via HTTP instead of HTTPS:

http://192.168.1.100/setup

Use the server's IP address or internal hostname.

When installing agents on LAN clients, use the HTTP URL or just copy the link from the Install Tab of the Client Detail page.

sudo python3 bbs-agent.py --server http://192.168.1.100 --api-key YOUR_API_KEY

Without SSL, all communication (including passwords and backup data) is unencrypted. Only use --no-ssl on trusted, isolated networks.

For better security on LANs:

1. Generate a self-signed certificate
2. Configure Apache manually for HTTPS
3. Update agent configurations to trust the self-signed cert

(This is an advanced configuration not covered by the automated installer.)

Symptom: apt errors, package not found

Solution:

sudo apt update
sudo apt upgrade
sudo ./bbs-install

Symptom: Red X on directory permission checks

Solution:

sudo chown -R www-data:www-data /var/www/bbs
sudo chown -R www-data:www-data /var/bbs/home
sudo chmod -R 755 /var/www/bbs

Symptom: Browser shows "Not Found"

Solution:

1. Verify Apache is running: sudo systemctl status apache2
2. Check Apache config: sudo apache2ctl configtest
3. Restart Apache: sudo systemctl restart apache2
4. Check /var/www/bbs/public exists and contains index.php

Symptom: "Could not connect to database" error

Solution:

1. Verify MySQL is running: sudo systemctl status mysql
2. Test manual connection: sudo mysql -u root -p
3. Create database manually if needed:

   sudo mysql -e "CREATE DATABASE IF NOT EXISTS bbs;"

See Troubleshooting for more common issues.

Once installation is complete:

1. Read the Getting Started guide
2. Configure Settings (SMTP, timezone, etc.)
3. Set up Two-Factor Authentication
4. Add clients and create backup plans
5. Optionally configure Remote Storage to back up directly to remote SSH hosts like rsync.net, BorgBase, or Hetzner

To completely remove BBS:

sudo rm -rf /var/www/bbs
sudo rm -rf /var/bbs
sudo rm /etc/apache2/sites-available/bbs.conf
sudo a2dissite bbs
sudo systemctl reload apache2
sudo mysql -e "DROP DATABASE bbs;"
sudo crontab -l | grep -v scheduler | sudo crontab -

Warning: This deletes all backups and configuration. Export any data you need first.