This quick-start guide walks you through creating your first backup with BBS. You'll add a client machine, install the agent, create a repository, and configure an automated backup plan.

Prerequisites: You've completed Installation and can log into BBS.

Navigate to your BBS server in a web browser:

https://backups.example.com

Log in with the administrator credentials you created during setup.

Screenshot: BBS login page with email and password fields

After logging in, you'll see the dashboard.

Screenshot: Dashboard showing no clients or backups yet

Clients represent the machines you want to back up (servers, workstations, etc.).

1. Click Clients in the top navigation menu
2. Click the Add Client button

Screenshot: Clients page with "Add Client" button highlighted

3. In the "Add Client" modal, enter:
   • Client Name: A descriptive name (e.g., "Web Server 01", "Database Server", "John's Laptop")

Screenshot: Add Client modal with name field

4. Click Create Client

The client is created and you'll see a one-time API key displayed.

Screenshot: API key display modal showing the key and copy button

Important: Copy this API key now. It's shown only once and is required to install the agent.

5. Click Copy API Key to copy it to your clipboard

The BBS agent is a Python script that runs on the machine being backed up. It polls the BBS server for backup tasks and executes them.

On the client machine, download the agent script:

curl -sSL https://backups.example.com/get-agent -o bbs-agent.py
chmod +x bbs-agent.py

(Replace backups.example.com with your BBS server's hostname)

Run the agent with the --server and --api-key flags to register it:

sudo python3 bbs-agent.py --server https://backups.example.com --api-key YOUR_API_KEY

Replace:

• https://backups.example.com with your BBS server URL
• YOUR_API_KEY with the API key you copied in Step 2

What this does:

• Registers the agent with the BBS server
• Creates a systemd service to run the agent automatically
• Generates SSH keys for BorgBackup communication
• Starts the agent service

You should see output like:

[INFO] Registering agent with server...
[INFO] Registration successful
[INFO] Installing systemd service...
[INFO] Service installed: bbs-agent.service
[INFO] Starting agent...
[INFO] Agent is running

Back in the BBS web interface, go to Clients. You should see your client listed with a green "Online" status indicator.

Screenshot: Client list showing newly registered client with green online status

Click on the client name to view its detail page.

Screenshot: Client detail page showing Overview tab with system information

The Overview tab shows system information reported by the agent (hostname, OS, IP address, disk usage, etc.).

Troubleshooting:

• If the client shows "Offline", check the agent logs on the client machine: sudo journalctl -u bbs-agent -f
• Verify the client can reach the BBS server: curl https://backups.example.com
• Check firewall rules on both the client and server

See Agent Setup for detailed agent installation instructions and troubleshooting.

Repositories are BorgBackup storage locations on the BBS server. Each client typically has one or more repositories.

1. On the client detail page, click the Repositories tab
2. Click Create Repository

Screenshot: Repositories tab with "Create Repository" button

3. In the "Create Repository" modal, enter:
   • Repository Name: A descriptive name (e.g., "main", "daily-backups", "system")
   • Encryption: Select an encryption mode:
     • Repokey (recommended): Encryption key stored in the repository (backed up with borg key export)
     • Keyfile: Encryption key stored separately on the client
     • None: No encryption (not recommended unless already encrypting at disk level)
   • Passphrase: If using encryption, enter a strong passphrase (store this securely!)

Screenshot: Create Repository modal with name, encryption, and passphrase fields

4. Click Create Repository

BBS creates the repository and initializes it via the agent. This takes 5-15 seconds.

When complete, the repository appears in the Repositories tab.

Screenshot: Repositories tab showing newly created repository with status "Ready"

Important: If you chose encryption, save your passphrase securely. Without it, your backups are unrecoverable. Consider using a password manager or printing and storing it in a safe.

See Repositories for more details on repository management.

Backup plans define what to back up, when to back up, and how long to retain backups.

1. On the client detail page, click the Schedules tab
2. Click Create Backup Plan

Screenshot: Schedules tab with "Create Backup Plan" button

3. In the "Create Backup Plan" form, configure:

   Basic Settings:

   • Plan Name: Descriptive name (e.g., "Daily System Backup", "Hourly Database Backup")
   • Repository: Select the repository you created in Step 4
   • Enabled: Check this to activate the plan

   Paths to Backup:

   • Click Add Path
   • Enter a directory path to back up (e.g., /home, /var/www, /etc)
   • Click Add Path again to add more directories
   • You can exclude specific subdirectories using the Exclude Patterns field (e.g., *.tmp, /var/cache, node_modules)

   Schedule:

   • Frequency: Choose when backups run (Hourly, Daily, Weekly, Monthly)
   • Time: Specify the time of day (for Daily/Weekly/Monthly) or interval (for Hourly)
   • Day of Week: (for Weekly backups)
   • Day of Month: (for Monthly backups)

   Retention Policy:

   • Keep Daily: Number of daily backups to retain
   • Keep Weekly: Number of weekly backups to retain
   • Keep Monthly: Number of monthly backups to retain
   • Keep Yearly: Number of yearly backups to retain

   Example retention: 7 daily, 4 weekly, 6 monthly = ~6 months of history

Screenshot: Create Backup Plan form showing all fields filled out

4. Click Create Plan

The backup plan is created and appears in the Schedules tab.

Screenshot: Schedules tab showing newly created backup plan with next scheduled run time

See Backup Plans for advanced options (compression, pre/post hooks, plugins, etc.).

Backup plans run automatically at their scheduled time. To test immediately:

1. In the Schedules tab, find your backup plan
2. Click the Run Now button

Screenshot: Backup plan row with "Run Now" button highlighted

A backup job is queued and sent to the agent.

3. Click Queue in the top navigation to monitor progress

Screenshot: Queue page showing backup job in "Running" status with progress bar

You'll see:

• Job status (Queued → Sent → Running → Completed)
• Progress percentage
• Files processed
• Data transferred
• Estimated time remaining

When the backup completes, the status changes to "Completed" (green).

Screenshot: Queue page showing completed backup job with green status and statistics

Troubleshooting:

• If the job stays in "Queued" status, check that the agent is online (Clients page)
• If the job fails, click on it to view error details
• Check agent logs on the client: sudo journalctl -u bbs-agent -f

See Queue and Jobs for details on monitoring and troubleshooting jobs.

After the first backup completes:

1. Go to the client detail page
2. Click the Repositories tab
3. Click on your repository name

Screenshot: Repository detail page showing list of backup archives

You'll see a list of backup archives (one per backup run), showing:

• Archive name (timestamp-based)
• Date/time created
• Number of files
• Original size
• Compressed size
• Deduplicated size

4. Click on an archive to browse its contents

Screenshot: Archive browser showing directory tree with file list

You can browse the full directory structure and restore individual files. See Restoring Files for details.

Congratulations! You've created your first automated backup with BBS.

• Add more clients: Repeat Steps 2-6 for each machine you want to back up
• Add more backup plans: Create multiple plans for different data sets (e.g., hourly for databases, daily for user files)
• Set up database backups: Use the Database Backups to automatically dump MySQL/PostgreSQL databases before backing them up
• Configure S3 sync: Set up S3 Offsite Sync to copy repositories to Amazon S3 or compatible storage for offsite protection

Get alerts when backups fail:

• Go to Settings → Notifications
• Configure email or webhook notifications
• See Notifications for details

• Enable Two-Factor Authentication for your account
• Add additional users with appropriate permissions (see User Management)
• Review Settings for security options (session timeout, API rate limiting, etc.)

• Check the Dashboard regularly for backup status summary
• Review the Queue and Jobs page for recent activity
• Set up Notifications for proactive alerting

After initial setup, you'll typically:

• Monitor backups: Check the Dashboard and Queue and Jobs page
• Restore files: Browse archives and restore specific files (see Restoring Files)
• Adjust schedules: Modify backup plans as needs change (see Backup Plans)
• Add/remove clients: Manage the list of machines being backed up (see Managing Clients)
• Review retention: Adjust how long backups are kept to balance storage and recovery needs
• Update BBS: Keep the server software up to date (see Updating BBS)

If you run into issues:

1. Check the Troubleshooting page
2. Review agent logs on the client: sudo journalctl -u bbs-agent -f
3. Review BBS logs on the server: sudo tail -f /var/log/bbs/scheduler.log
4. Search GitHub Issues for similar problems
5. Open a new issue if you've found a bug

• Managing Clients - Detailed client management
• Agent Setup - Advanced agent configuration
• Repositories - Repository management and best practices
• Backup Plans - Advanced backup plan options
• Restoring Files - File restoration walkthrough
• Plugins - Using and configuring plugins
• Settings - Configuring BBS server settings