Getting Started

Getting Started

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.

Step 1: Log In

Navigate to your BBS server in a web browser:

https://backups.example.com

Log in with the administrator credentials you created during setup.

After logging in, you'll see the dashboard.

Step 2: Add Your First Client

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

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

4. Click Create Client

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

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

Step 3: Install the Agent on the Client Machine

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.

Install the Agent

On the client machine, run the one-line installer (it downloads the agent, registers it, and installs a system service). The easiest way is to copy the exact command from the client's Install tab in the BBS web interface — it comes pre-filled with your server URL and API key:

curl -s https://backups.example.com/get-agent | sudo bash -s -- --server https://backups.example.com --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:

• Installs Borg (if needed) and downloads the agent to /opt/bbs-agent
• Registers the agent with the BBS server
• Generates SSH keys for BorgBackup communication
• Installs and starts a system service (systemd on most Linux distros) so the agent keeps running

Note: The agent must run on a real host (or a dedicated agent container) with a service manager. Don't install it inside the BBS server container itself — containers have no systemd, so the agent can't keep running and the client will drop to "Offline" after registration. BBS never backs up data mounted into its own container; backups always run through an agent. If the data lives on a NAS/Docker host, install the agent on that host, or use the Docker Agent Setup to run the agent as its own container with your data mounted into it.

Verify the Agent is Running

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

Click on the client name to view its detail page.

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 Linux Agent Setup for detailed agent installation instructions and troubleshooting.

Step 4: Create a Repository

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

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!)

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.

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.

Step 5: Create a Backup Plan

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

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

4. Click Create Plan

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

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

Step 6: Run Your First Backup

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

A backup job is queued and sent to the agent.

3. Click Queue in the top navigation to monitor progress

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).

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.

Step 7: Verify the Backup

After the first backup completes:

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

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

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

Next Steps

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

Expand Your Backups

• 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

Configure Notifications

Get alerts when backups fail:

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

Secure Your Installation

• 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.)

Automate Monitoring

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

Common Tasks

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)

Getting Help

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

Additional Documentation

• Managing Clients - Detailed client management
• Linux 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