Skip to main content

Borgmatic for beginners

<h1>

Borgmatic UI - Beginner's Guide</h1>


<p class="callout info">

Welcome to Borgmatic UI! This guide will help you understand the basics of backing up your data using this powerful yet easy-to-use backup management interface.</p>


<h2>

Understanding Key Concepts</h2>


<p>

Before diving in, it's important to understand the terminology used throughout the application. These terms come from the underlying backup tools (Borg and Borgmatic) and understanding them will make everything much clearer.</p>


<hr>

<h3>

🗄️ Repository</h3>


<p><strong>

What is it?</strong> A <strong>Repository</strong> is the <em>destination</em> where your backups are stored. Think of it as a secure vault or storage container that holds all your backup data.</p>


<p><strong>

Key points:</strong></p>

<ul>
        <li>
  • A repository is created once and can hold many backups over time</li>
    •     <li>
  • Repositories are encrypted by default - you'll set a passphrase when creating one</li>
    •     <li>
  • You can have multiple repositories (e.g., one local, one remote)</li>
    •     <li>
  • Repositories can be stored locally (on your server) or remotely (SSH server, cloud storage)</li>
    • </ul>

<p class="callout warning"><strong>

Important:</strong> Never lose your repository passphrase! Without it, your backup data cannot be recovered.</p>


<hr>

<h3>

💾 Backup (Backup Job)</h3>


<p><strong>

What is it?</strong> A <strong>Backup</strong> (or Backup Job) is a <em>configuration</em> that defines:</p>

<ul>
        <li><strong>
  • What</strong> to back up (which files and folders)</li>
    •     <li><strong>
  • Where</strong> to store it (which repository)</li>
    •     <li><strong>
  • How</strong> to back it up (compression, exclusions, etc.)</li>
    •     <li><strong>
  • When</strong> to run (if scheduled)</li>
    • </ul>

<p><strong>

Example:</strong> You might create a backup job called "Website Backup" that backs up <code>/var/www</code> to your remote repository every night at 2 AM.</p>


<hr>

<h3>

📦 Archive</h3>


<p><strong>

What is it?</strong> An <strong>Archive</strong> is a single <em>snapshot</em> of your data at a specific point in time. Every time a backup job runs successfully, it creates a new archive.</p>


<p><strong>

Key points:</strong></p>

<ul>
        <li>
  • Archives are stored inside repositories</li>
    •     <li>
  • Each archive has a unique name (usually including a timestamp)</li>
    •     <li>
  • Archives are deduplicated - only changed data is stored, saving space</li>
    •     <li>
  • You can browse, restore, or delete individual archives</li>
    • </ul>

<p><strong>

Analogy:</strong> If a Repository is a photo album, then Archives are individual photos. Each photo captures a moment in time, and the album holds them all together.</p>


<hr>

<h2>

⏰ Schedules</h2>


<p>

Schedules allow you to automate your backups so they run without manual intervention.</p>


<h3>

How Schedules Work</h3>

<ul>
        <li>
  • Schedules are attached to backup jobs</li>
    •     <li>
  • You can set backups to run hourly, daily, weekly, or with custom cron expressions</li>
    •     <li>
  • Scheduled backups run automatically in the background</li>
    •     <li>
  • You'll see the status and history of scheduled runs in the dashboard</li>
    • </ul>

<h3>

Common Schedule Patterns</h3>

<table>
<thead>
      <tr>
            <th>Pattern</th>
            <th>Description</th>
            <th>
</tr>
  </thead>
    <tbody>
        <tr>
            <td>
            <td>
            <td>
</tr>
        <tr>
            <td>
            <td>
            <td>
</tr>
        <tr>
            <td>
            <td>
            <td>
</tr>
Pattern Description Best For</th>
Daily at 2:00 AM</td> Runs once per day during low-activity hours</td> Most use cases</td>
Every 6 hours</td> Runs 4 times per day</td> Frequently changing data</td>
Weekly on Sunday</td> Runs once per week</td> Large, stable datasets</td>
  </tbody>
</table>

<hr>

<h2>

🔑 SSH Keys</h2>


<p>

SSH Keys are used for secure, passwordless authentication when connecting to remote servers for backup storage.</p>


<h3>

Why Use SSH Keys?</h3>

<ul>
        <li><strong>
  • Security:</strong> More secure than passwords</li>
    •     <li><strong>
  • Automation:</strong> Required for scheduled backups to remote servers (no password prompts)</li>
    •     <li><strong>
  • Convenience:</strong> No need to enter passwords repeatedly</li>
    • </ul>

<h3>

How to Set Up SSH Keys</h3>

<ol>
        <li>
  1. Go to <strong>SSH Key Management</strong> in the sidebar</li>
    2.     <li>
  2. Either <strong>Generate</strong> a new key pair or <strong>Import</strong> an existing key</li>
    3.     <li>
  3. Copy the <strong>public key</strong> to your remote server's <code>~/.ssh/authorized_keys</code></li>
    4.     <li>
  4. Test the connection to verify it works</li>
    5. </ol>

<p class="callout info"><strong>

Tip:</strong> When importing a key, you can select a file from the server or upload from your computer using the buttons in the import dialog.</p>


<hr>

<h2>

🗃️ Storage Types</h2>


<p>

When creating a repository, you can choose from several storage types depending on where you want to store your backups.</p>


<h3>

Local Repository</h3>

<p><strong>

Path format:</strong> <code>/path/to/repository</code></p>

<ul>
        <li>
  • Stored on the same server or a mounted drive</li>
    •     <li>
  • Fastest backup and restore speeds</li>
    •     <li>
  • Best for: Quick backups, staging before cloud sync</li>
    • </ul>

<h3>

SSH/SFTP Repository</h3>

<p><strong>

Path format:</strong> <code>ssh://user@hostname/path/to/repository</code></p>

<ul>
        <li>
  • Stored on a remote server via SSH</li>
    •     <li>
  • Requires SSH key or password authentication</li>
    •     <li>
  • Best for: Off-site backups, dedicated backup servers</li>
    • </ul>

<h3>

Cloud Storage (with Rclone)</h3>

<p>

For cloud storage like Amazon S3, Backblaze B2, Google Drive, etc.</p>


<h4>

Option 1: Local + Cloud Sync (Recommended)</h4>

<ul>
        <li>
  • Backups are stored locally first</li>
    •     <li>
  • Automatically synced to cloud after each backup</li>
    •     <li>
  • Faster backups, cloud redundancy</li>
    • </ul>

<h4>

Option 2: Native Cloud (Borg 2.x only)</h4>

<ul>
        <li>
  • Borg 2.x can write directly to S3-compatible storage</li>
    •     <li>
  • No Rclone required</li>
    •     <li>
  • Simplest cloud setup</li>
    • </ul>

<hr>

<h2>

🔄 How to Restore (Retrieve) Backups</h2>


<p>

Restoring your data is just as important as backing it up. Here's how to retrieve files from your backups.</p>


<h3>

Step 1: Navigate to Archives</h3>

<ol>
        <li>
  1. Go to <strong>Archives</strong> in the sidebar</li>
    2.     <li>
  2. Select the repository containing your backup</li>
    3.     <li>
  3. You'll see a list of all archives (snapshots) in that repository</li>
    4. </ol>

<h3>

Step 2: Browse the Archive</h3>

<ol>
        <li>
  1. Click on an archive to open the <strong>Archive Browser</strong></li>
    2.     <li>
  2. Navigate through folders just like a file explorer</li>
    3.     <li>
  3. Preview text files directly in the browser</li>
    4. </ol>

<h3>

Step 3: Restore Files</h3>

<p>

You have three options when restoring:</p>


<table>
<thead>
        <tr>
            <th>Option</th>
            <th>Description</th>
            <th>
</tr>
  </thead>
    <tbody>
        <tr>
            <td><strong>
            <td>
            <td>
</tr>
        <tr>
            <td><strong>Download</strong></td>
            <td>
            <td>
</tr>
        <tr>
            <td><strong>
            <td>
            <td>
</tr>
Option Description Use Case</th>
Restore to New Location</strong></td> Extract files to a folder you choose</td> Safest option - review before replacing</td>
Download Download files to your computer (folders are zipped)</td> Quick access, small files</td>
Restore to Original Location</strong></td> Put files back where they came from</td> Full restore after data loss</td>
    </tbody>
</table>

<p class="callout warning"><strong>

Caution:</strong> "Restore to Original Location" will overwrite existing files. Use with care!</p>


<hr>

<h2>

🚀 Quick Start Guide</h2>


<p>

Ready to create your first backup? Follow these steps:</p>


<h3>

1. Create a Repository</h3>

<ol>
        <li>
  1. Go to <strong>Repositories</strong> → <strong>Create Repository</strong></li>
    2.     <li>
  2. Choose a storage type (Local is easiest to start)</li>
    3.     <li>
  3. Set a path (e.g., <code>/host/backups/my-repo</code>)</li>
    4.     <li>
  4. Enter a strong passphrase and save it somewhere safe!</li>
    5.     <li>
  5. Click <strong>Create</strong></li>
    6. </ol>

<h3>

2. Create a Backup Job</h3>

<ol>
        <li>
  1. Go to <strong>Backups</strong> → <strong>Create Backup</strong></li>
    2.     <li>
  2. Give it a name (e.g., "My Documents")</li>
    3.     <li>
  3. Select your repository</li>
    4.     <li>
  4. Add source paths (what to back up)</li>
    5.     <li>
  5. Optionally set a schedule</li>
    6.     <li>
  6. Click <strong>Create</strong></li>
    7. </ol>

<h3>

3. Run Your First Backup</h3>

<ol>
        <li>
  1. Find your backup job in the list</li>
    2.     <li>
  2. Click the <strong>Run</strong> button</li>
    3.     <li>
  3. Watch the progress in the dashboard</li>
    4.     <li>
  4. Once complete, you'll have your first archive!</li>
    5. </ol>

<h3>

4. Verify Your Backup</h3>

<ol>
        <li>
  1. Go to <strong>Archives</strong></li>
    2.     <li>
  2. Select your repository</li>
    3.     <li>
  3. Click on the archive to browse its contents</li>
    4.     <li>
  4. Confirm your files are there</li>
    5. </ol>

<hr>

<h2>

💡 Tips for Beginners</h2>


    <ul>
        <li><strong>
  • Start small:</strong> Begin with a small folder to test the process</li>
    •     <li><strong>
  • Use descriptive names:</strong> Name your backups and repositories clearly</li>
    •     <li><strong>
  • Test restores:</strong> Regularly practice restoring files to ensure your backups work</li>
    •     <li><strong>
  • Multiple destinations:</strong> Consider both local and remote repositories for redundancy</li>
    •     <li><strong>
  • Monitor the dashboard:</strong> Check regularly that scheduled backups are running</li>
    •     <li><strong>
  • Keep passphrases safe:</strong> Store repository passphrases in a password manager</li>
    • </ul>

<hr>

<h2>

📚 Glossary</h2>


<table>
<thead>
<tr>
<th>Term</th>
            <th>Definition</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><strong>Borg</strong></td>
            <td>
</tr>
        <tr>
            <td><strong>Borgmatic</strong></td>
            <td>
</tr>
        <tr>
            <td><strong>Deduplication</strong></td>
            <td>
</tr>
        <tr>
            <td><strong>Archive</strong></td>
            <td>
</tr>
        <tr>
            <td><strong>Repository</strong></td>
            <td>
</tr>
        <tr>
            <td><strong>Passphrase</strong></td>
            <td>
</tr>
        <tr>
            <td><strong>Rclone</strong></td>
            <td>
</tr>
        <tr>
            <td><strong>
            <td>
</tr>
        <tr>
            <td><strong>Retention</strong></td>
            <td>
</tr>
        <tr>
            <td><strong>Pruning</strong></td>
            <td>
</tr>
Term Definition
Borg The underlying backup program that handles deduplication and encryption</td>
Borgmatic A wrapper around Borg that simplifies configuration and automation</td>
Deduplication Only storing unique data chunks, saving significant storage space</td>
Archive A single backup snapshot at a point in time</td>
Repository The storage location containing all your archives</td>
Passphrase The password used to encrypt/decrypt your repository</td>
Rclone A tool for syncing files to cloud storage providers</td>
SSH Key</strong></td> A cryptographic key pair for secure, passwordless server authentication</td>
Retention Rules for how long to keep old archives before pruning them</td>
Pruning Removing old archives according to retention rules to save space</td>
  </tbody>
</table>

<hr>

<p class="callout success"><strong>

Congratulations!</strong> You now have a solid understanding of Borgmatic UI. Remember: a backup is only as good as its last successful restore test. Happy backing up! 🎉</p>


Back to top