Quick Start Guide

This guide walks you through creating your first backup in Zerobyte, from initial setup to verifying a successful backup.

This guide assumes you’ve already installed Zerobyte and can access the web interface.

Overview

Setting up a backup involves three key steps:

Add a Volume

Define the source data you want to backup

Create a Repository

Set up an encrypted storage destination for your backups

Configure a Backup Job

Connect your volume to your repository with scheduling and retention policies

Let’s walk through each step.

First-Time Setup

Create Your Admin Account

When you first access Zerobyte at http://<your-server-ip>:4096, you’ll be prompted to create an admin account:

Open Zerobyte

Navigate to the URL you configured in BASE_URL during installation

Complete Registration

Enter your desired username, email, and password for the admin account

Save Restic Password

After registration, you’ll be prompted to download your Restic encryption password. This is critical - store it safely!

Critical: The Restic password is used to encrypt all your backups. If you lose this password, you will not be able to restore your data. Save it in a password manager or secure location immediately.

Step 1: Add a Volume

A volume represents the source data you want to backup. Zerobyte supports various volume types including local directories, NFS shares, SMB shares, WebDAV, and SFTP.

Adding a Local Directory

For this quick start, we’ll add a local directory. First, ensure the directory is mounted into your Zerobyte container.

Mount the Directory

Update your docker-compose.yml to mount the directory you want to backup:

docker-compose.yml

services:
  zerobyte:
    image: ghcr.io/nicotsx/zerobyte:v0.29
    container_name: zerobyte
    restart: unless-stopped
    # ... other configuration ...
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /var/lib/zerobyte:/var/lib/zerobyte
      - /path/to/your/data:/data  # Add this line

Restart the container to apply changes:

docker compose down
docker compose up -d

Create the Volume in Zerobyte

Navigate to Volumes

In the Zerobyte web interface, click on Volumes in the sidebar

Create New Volume

Click the Create Volume button

Configure Volume

Fill in the volume details:

Name: Give it a descriptive name (e.g., “My Documents”)
Type: Select “Directory”
Path: Enter the container path (e.g., /data)

Save Volume

Click Create to save the volume configuration

The volume path must match the path inside the container, not the host path. In the example above, even though the host path is /path/to/your/data, you would enter /data as the volume path.

Adding Remote Volumes

Zerobyte also supports remote volume types:

NFS
SMB/CIFS
WebDAV
SFTP

Configure an NFS share:

Host: NFS server hostname or IP
Export: NFS export path (e.g., /mnt/data)
Options: Mount options (optional, e.g., vers=4,soft)

Configure an SMB/CIFS share:

Host: SMB server hostname or IP
Share: Share name
Username: SMB username
Password: SMB password (can use env:// or file:// secrets)
Domain: Windows domain (optional)

Remote volumes require the full installation with SYS_ADMIN capability and /dev/fuse device. See the Installation guide for details.

Step 2: Create a Repository

A repository is the encrypted storage destination where your backups will be stored. Zerobyte supports multiple repository backends.

Creating a Local Repository

For this quick start, we’ll create a local repository:

Navigate to Repositories

Click on Repositories in the sidebar

Create New Repository

Click the Create Repository button

Configure Repository

Fill in the repository details:

Name: Descriptive name (e.g., “Local Backup Repository”)
Type: Select “Local”
Path: Enter a path for the repository (e.g., /var/lib/zerobyte/repositories/local-backup)

Initialize Repository

Click Create and Initialize. Zerobyte will create and initialize the Restic repository with encryption.

Repository initialization may take a few seconds. Zerobyte will create the repository structure and configure encryption using your Restic password.

Cloud Storage Repositories

For production use, consider using cloud storage for offsite backups:

S3-Compatible
Google Cloud Storage
Azure Blob
rclone

Configure S3-compatible storage (AWS S3, MinIO, Wasabi, Backblaze B2, etc.):

Repository Configuration

Type: S3
Endpoint: s3.amazonaws.com (or custom endpoint)
Region: us-east-1
Bucket: my-backup-bucket
Path: backups/zerobyte (optional prefix)
Access Key ID: AKIAIOSFODNN7EXAMPLE
Secret Access Key: env://S3_SECRET_KEY

Use env:// secret references to avoid storing credentials in the database. See Installation - Docker Secrets.

Configure Google Cloud Storage:

Repository Configuration

Type: Google Cloud Storage
Project ID: my-project-id
Bucket: my-backup-bucket
Path: backups/zerobyte (optional prefix)
Service Account JSON: Upload credentials file

Configure Azure Blob Storage:

Repository Configuration

Type: Azure Blob Storage
Account Name: myaccountname
Container: backups
Path: zerobyte (optional prefix)
Account Key: env://AZURE_ACCOUNT_KEY

Configure rclone-based storage (requires rclone config mounted):

Repository Configuration

Type: rclone
Remote: gdrive (must exist in rclone config)
Path: backups/zerobyte

rclone must be configured on the host and mounted into the container. See Installation - Mounting rclone Configuration.

Step 3: Create a Backup Job

A backup job connects a volume to a repository and defines when and how backups should run.

Navigate to Backups

Click on Backups in the sidebar

Create New Backup Job

Click the Create Backup Job button

Configure Basic Settings

Name: Descriptive name (e.g., “Daily Documents Backup”)
Volume: Select the volume you created earlier
Repository: Select the repository you created earlier
Enabled: Toggle on to enable the job

Configure Schedule

Set when backups should run:

Schedule Type: Choose “Simple” or “Cron”
Simple: Select daily, weekly, etc.
Cron: Enter cron expression (e.g., 0 2 * * * for 2 AM daily)

Common Cron Patterns

0 2 * * * - Daily at 2:00 AM
0 2 * * 0 - Weekly on Sunday at 2:00 AM
0 2 1 * * - Monthly on the 1st at 2:00 AM
0 */6 * * * - Every 6 hours
0 0 * * 1-5 - Weekdays at midnight

Configure Retention Policy

Define how long backups should be kept:

Example Retention Policy

Keep Last: 7 daily backups
Keep Last: 4 weekly backups
Keep Last: 6 monthly backups
Keep Last: 1 yearly backup

Retention policies automatically prune old backups to save storage space. Restic’s deduplication ensures you only store unique data.

Configure Paths (Optional)

By default, the entire volume is backed up. You can specify:

Include paths: Only backup specific subdirectories
Exclude paths: Exclude specific files or patterns (e.g., *.tmp, node_modules/)

Advanced Options (Optional)

Configure advanced settings:

Compression: Enable to reduce backup size (slight CPU overhead)
Bandwidth Limit: Limit upload/download speed
Parallel Upload: Number of parallel file uploads

Save Backup Job

Click Create to save the backup job. It will run according to the schedule you configured.

Step 4: Run Your First Backup

Instead of waiting for the scheduled time, let’s run the backup immediately:

Find Your Backup Job

In the Backups section, locate the job you just created

Run Backup Manually

Click the Run Now button (play icon) next to your backup job

Monitor Progress

Watch the backup progress in real-time:

Files scanned
Data processed
Upload progress
Estimated time remaining

Wait for Completion

The backup will show a success status when complete. Duration depends on data size and storage speed.

During the first backup, all data is uploaded. Subsequent backups are much faster due to Restic’s incremental backup and deduplication.

Step 5: Verify Your Backup

After the backup completes, verify it was successful:

View Backup Details

Click on your backup job to view details

Check Snapshots

You should see at least one snapshot listed with:

Snapshot timestamp
Number of files backed up
Total size
New data added (vs. deduplicated)

Browse Backup Contents

Click on a snapshot to browse its contents. You can:

Navigate the directory structure
View file sizes and modification times
Search for specific files

Test Restore (Optional)

For peace of mind, test restoring a file:

Select a file from the snapshot browser
Click Restore
Choose restore location
Verify the file was restored correctly

By default, restored files are placed back in their original location. Be careful not to overwrite current files. You can specify an alternate restore path if needed.

Understanding Backup Status

Your backup dashboard shows the status of all backup jobs:

Status	Description
Success	Backup completed without errors
Running	Backup currently in progress
Failed	Backup encountered an error (check logs)
Scheduled	Backup waiting for next scheduled run
Disabled	Backup job is disabled and won’t run

Click on any backup job to view detailed logs, snapshot history, and statistics.

Monitoring Your Backups

Zerobyte provides several ways to monitor backup health:

Dashboard Overview

The main dashboard shows:

Total number of backup jobs
Storage usage across all repositories
Recent backup activity
Failed backups requiring attention

Backup Job Details

Each backup job displays:

Last run time and status
Next scheduled run
Number of snapshots
Total backup size
Backup duration trends

Repository Health

Repository details show:

Total size and file count
Deduplication ratio
Number of snapshots
Integrity check status

Regularly check repository integrity using the Check button in the repository details. This verifies backup data hasn’t been corrupted.

Next Steps

Now that you have a working backup, consider:

Add More Volumes

Back up additional directories or remote shares

Set Up Cloud Storage

Configure offsite backups to S3, Google Cloud, or Azure

Configure Notifications

Get alerted when backups fail or complete

Optimize Retention

Fine-tune retention policies to balance storage and history

Common Tasks

Restoring Data

To restore data from a backup:

Navigate to Backup

Go to Backups and select the backup job containing the data you need

Select Snapshot

Choose the snapshot from the time period you want to restore from

Browse and Select

Browse the file tree and select files/folders to restore

Choose Restore Location

Decide whether to restore to original location or specify a new path

Restore

Click Restore and wait for the operation to complete

Pausing a Backup Job

To temporarily stop a backup from running:

Navigate to the backup job
Toggle the Enabled switch to off
The job will skip scheduled runs until re-enabled

Viewing Backup Logs

To troubleshoot issues or view detailed backup information:

Click on a backup job
Navigate to the Logs tab
View detailed output from Restic including:
- Files processed
- Errors encountered
- Performance statistics

Deleting Old Snapshots

Backups are automatically pruned according to retention policies, but you can manually delete snapshots:

Navigate to backup job
Select the snapshot you want to delete
Click Delete Snapshot
Confirm deletion

Deleting snapshots is irreversible. Ensure you don’t need the data before deleting.

Troubleshooting

Backup Failed: Permission Denied

Ensure the volume directory has proper permissions:

# On the host system
sudo chmod -R 755 /path/to/your/data

Backup Running Slowly

Check:

Network bandwidth (for cloud repositories)
Disk I/O performance
Enable compression if uploading large compressible files
Adjust parallel upload settings

Repository Initialization Failed

Verify:

Repository path is writable
For cloud repositories, credentials are correct
Network connectivity to cloud storage

Can’t Find Mounted Directory

Ensure:

Directory is mounted in docker-compose.yml
Container was restarted after mounting: docker compose restart
Path matches the container path, not host path

Getting Help

If you encounter issues:

Check Logs

View detailed logs with docker compose logs -f zerobyte

GitHub Issues

Report bugs or request features at github.com/nicotsx/zerobyte/issues

Documentation

Explore the full documentation for advanced topics

Community

Join discussions and get help from other users

When reporting issues, include:

Zerobyte version (visible in UI footer)
Docker and Docker Compose versions
Relevant logs from docker compose logs zerobyte
Steps to reproduce the issue

Conclusion

You’ve successfully:

✅ Created an admin account and secured your Restic password
✅ Added a volume to backup
✅ Created a repository for encrypted storage
✅ Configured and ran your first backup job
✅ Verified your backup was successful

Your data is now protected with encrypted, deduplicated backups. Zerobyte will continue to run backups automatically according to your schedule.

Important Reminder: Keep your Restic encryption password safe! Without it, you cannot restore your backups. Consider storing it in multiple secure locations.

Get Started

Core Concepts

Configuration

Guides

Advanced

​Quick Start Guide

​Overview

​First-Time Setup

​Create Your Admin Account

​Step 1: Add a Volume

​Adding a Local Directory

​Mount the Directory

​Create the Volume in Zerobyte

​Adding Remote Volumes

​Step 2: Create a Repository

​Creating a Local Repository

​Cloud Storage Repositories

​Step 3: Create a Backup Job

​Step 4: Run Your First Backup

​Step 5: Verify Your Backup

​Understanding Backup Status

​Monitoring Your Backups

​Dashboard Overview

​Backup Job Details

​Repository Health

​Next Steps

Add More Volumes

Set Up Cloud Storage

Configure Notifications

Optimize Retention

​Common Tasks

​Restoring Data

​Pausing a Backup Job

​Viewing Backup Logs

​Deleting Old Snapshots

​Troubleshooting

​Backup Failed: Permission Denied

​Backup Running Slowly

​Repository Initialization Failed

​Can’t Find Mounted Directory

​Getting Help

Check Logs

GitHub Issues

Documentation

Community

​Conclusion

Build docs developers (and LLMs) love

Quick Start Guide

Overview

First-Time Setup

Create Your Admin Account

Step 1: Add a Volume

Adding a Local Directory

Mount the Directory

Create the Volume in Zerobyte

Adding Remote Volumes

Step 2: Create a Repository

Creating a Local Repository

Cloud Storage Repositories

Step 3: Create a Backup Job

Step 4: Run Your First Backup

Step 5: Verify Your Backup

Understanding Backup Status

Monitoring Your Backups

Dashboard Overview

Backup Job Details

Repository Health

Next Steps

Common Tasks

Restoring Data

Pausing a Backup Job

Viewing Backup Logs

Deleting Old Snapshots

Troubleshooting

Backup Failed: Permission Denied

Backup Running Slowly

Repository Initialization Failed

Can’t Find Mounted Directory

Getting Help

Conclusion