Installation

Zerobyte runs as a Docker container and requires Docker and Docker Compose to be installed on your server.

Prerequisites

Install Docker

Ensure Docker is installed on your server. Visit docs.docker.com for installation instructions for your platform.

Install Docker Compose

Docker Compose is required for orchestration. It’s included with Docker Desktop or can be installed separately on Linux servers.

Check Installation

Verify your installation by running:

docker --version
docker compose version

Basic Installation

The standard installation includes remote mount support (NFS, SMB, WebDAV, SFTP) and requires elevated container capabilities.

1. Create docker-compose.yml

Create a docker-compose.yml file with the following configuration:

docker-compose.yml

services:
  zerobyte:
    image: ghcr.io/nicotsx/zerobyte:v0.29
    container_name: zerobyte
    restart: unless-stopped
    cap_add:
      - SYS_ADMIN
    ports:
      - "4096:4096"
    devices:
      - /dev/fuse:/dev/fuse
    environment:
      - TZ=Europe/Paris # Set your timezone here
      - BASE_URL=http://localhost:4096 # URL you will use to access Zerobyte
      - APP_SECRET=94bad46...c66e25d5c2b # Generate your own secret with `openssl rand -hex 32`
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /var/lib/zerobyte:/var/lib/zerobyte

Security Note: The SYS_ADMIN capability and /dev/fuse device are required for mounting remote filesystems (NFS, SMB, WebDAV, SFTP). If you only need local directory backups, see the Simplified Installation section below.

2. Configure Environment Variables

Update the environment variables in your docker-compose.yml:

openssl rand -hex 32

Required Environment Variables

Variable	Description	Example
`BASE_URL`	Required. The base URL where Zerobyte will be accessed. Used for cookie security and CORS.	`http://localhost:4096` or `https://zerobyte.example.com`
`APP_SECRET`	Required. A 32+ character random secret for encrypting sensitive data in the database. Generate with `openssl rand -hex 32`.	`94bad46...c66e25d5c2b`
`TZ`	Recommended. Timezone for accurate backup scheduling.	`Europe/Paris`, `America/New_York`, `UTC`

The BASE_URL determines cookie security behavior:

HTTP or IP addresses: Secure cookies disabled (allows local access)
HTTPS with domain: Secure cookies enabled (required for production)

Optional Environment Variables

Variable	Description	Default
`PORT`	Port the web interface listens on inside the container	`4096`
`RESTIC_HOSTNAME`	Hostname used by Restic in snapshots	`zerobyte`
`TRUSTED_ORIGINS`	Comma-separated list of additional trusted CORS origins	(none)
`LOG_LEVEL`	Logging verbosity: `debug`, `info`, `warn`, `error`	`info`
`SERVER_IDLE_TIMEOUT`	Server idle timeout in seconds	`60`
`RCLONE_CONFIG_DIR`	Path to rclone config directory inside container	`/root/.config/rclone`

3. Configure Volume Mounts

The essential volume mount stores Zerobyte’s data:

volumes:
  - /etc/localtime:/etc/localtime:ro
  - /var/lib/zerobyte:/var/lib/zerobyte

Important: Do not point /var/lib/zerobyte to a network share. This will cause permission issues and severe performance degradation. Always use local storage.

TrueNAS Users: The /var/lib path is ephemeral on TrueNAS and resets during system upgrades. Instead, create a dedicated ZFS dataset:

volumes:
  - /etc/localtime:/etc/localtime:ro
  - /mnt/tank/docker/zerobyte:/var/lib/zerobyte

This ensures your configuration, encryption keys, and database persist across upgrades.

4. Start Zerobyte

Start the container using Docker Compose:

docker compose up -d

Verify the container is running:

docker compose ps
docker compose logs -f zerobyte

5. Access the Web Interface

Once the container is running, access Zerobyte at the URL you specified in BASE_URL:

http://<your-server-ip>:4096

On first access, you’ll be prompted to create an admin account. This account will have full access to all backup management features.

Simplified Installation (No Remote Mounts)

If you only need to back up locally mounted directories and don’t require remote share mounting (NFS, SMB, WebDAV, SFTP), you can use a reduced-privilege deployment:

docker-compose.yml

services:
  zerobyte:
    image: ghcr.io/nicotsx/zerobyte:v0.29
    container_name: zerobyte
    restart: unless-stopped
    ports:
      - "4096:4096"
    environment:
      - TZ=Europe/Paris
      - BASE_URL=http://localhost:4096
      - APP_SECRET=94bad46...c66e25d5c2b
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /var/lib/zerobyte:/var/lib/zerobyte
      - /path/to/your/directory:/mydata

Trade-offs:

✅ Improved security by removing SYS_ADMIN capability
✅ Support for local directories mounted into the container
✅ All repository types still supported (local, S3, GCS, Azure, rclone)
❌ Cannot mount remote shares (NFS, SMB, WebDAV, SFTP) from within Zerobyte

If you need remote mount capabilities later, you can update your docker-compose.yml to add back the cap_add: SYS_ADMIN and devices: /dev/fuse:/dev/fuse directives.

Mounting Local Directories

To back up directories from your host system, mount them into the container:

volumes:
  - /etc/localtime:/etc/localtime:ro
  - /var/lib/zerobyte:/var/lib/zerobyte
  - /path/to/your/photos:/photos:ro
  - /path/to/your/documents:/documents:ro
  - /path/to/your/media:/media:ro

Use read-only mounts (:ro) when possible to prevent accidental modifications during backup operations.

After adding volume mounts, restart the container:

docker compose down
docker compose up -d

The mounted directories will be available inside the container at the specified paths (e.g., /photos, /documents, /media).

Advanced Configuration

Using Docker Secrets for Sensitive Data

Zerobyte supports reading secrets from environment variables or Docker secrets files instead of storing them encrypted in the database:

docker-compose.yml

services:
  zerobyte:
    image: ghcr.io/nicotsx/zerobyte:v0.29
    container_name: zerobyte
    restart: unless-stopped
    cap_add:
      - SYS_ADMIN
    devices:
      - /dev/fuse:/dev/fuse
    ports:
      - "4096:4096"
    environment:
      - TZ=Europe/Paris
      - BASE_URL=http://localhost:4096
      - APP_SECRET=94bad46...c66e25d5c2b
      - S3_ACCESS_KEY=your-access-key
      - S3_SECRET_KEY=your-secret-key
    secrets:
      - smb_password
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /var/lib/zerobyte:/var/lib/zerobyte

secrets:
  smb_password:
    file: ./secrets/smb_password.txt

When configuring volumes or repositories in the UI, you can reference these secrets:

env://S3_SECRET_KEY - Reads from environment variable S3_SECRET_KEY
file://smb_password - Reads from /run/secrets/smb_password

Mounting rclone Configuration

To use rclone-based repositories (Google Drive, Dropbox, OneDrive, etc.), mount your rclone configuration:

Configure rclone on Host

Install and configure rclone on your host system:

curl https://rclone.org/install.sh | sudo bash
rclone config

Mount Config into Container

Update your docker-compose.yml:

volumes:
  - /etc/localtime:/etc/localtime:ro
  - /var/lib/zerobyte:/var/lib/zerobyte
  - ~/.config/rclone:/root/.config/rclone:ro

Restart Container

docker compose down && docker compose up -d

Your rclone remotes will now be available when creating repositories in Zerobyte.

Reverse Proxy Setup

When running Zerobyte behind a reverse proxy (Nginx, Traefik, Caddy):

Set BASE_URL to your HTTPS domain: https://zerobyte.example.com
Ensure your proxy passes the X-Forwarded-Proto header
Secure cookies will automatically be enabled based on the https:// prefix

Nginx
Caddy
Traefik

nginx.conf

server {
    listen 443 ssl http2;
    server_name zerobyte.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:4096;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Caddyfile

zerobyte.example.com {
    reverse_proxy localhost:4096
}

docker-compose.yml

services:
  zerobyte:
    image: ghcr.io/nicotsx/zerobyte:v0.29
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.zerobyte.rule=Host(`zerobyte.example.com`)"
      - "traefik.http.routers.zerobyte.entrypoints=websecure"
      - "traefik.http.routers.zerobyte.tls.certresolver=letsencrypt"
      - "traefik.http.services.zerobyte.loadbalancer.server.port=4096"

Important: If you expose Zerobyte to the internet, bind the port to localhost only (127.0.0.1:4096:4096) and use a secure tunnel (SSH tunnel, Cloudflare Tunnel, etc.) with additional authentication.

Updating Zerobyte

To update to a new version:

# Pull the latest image
docker compose pull

# Restart with new image
docker compose up -d

# View logs
docker compose logs -f zerobyte

Always check the release notes before updating, especially for v0.x.x versions which may include breaking changes.

Troubleshooting

Container Won’t Start

Check logs: docker compose logs zerobyte
Verify APP_SECRET is set and at least 32 characters
Ensure /var/lib/zerobyte directory has correct permissions
Verify port 4096 is not already in use: netstat -tuln | grep 4096

Permission Issues

If you encounter permission errors:

# Fix ownership of data directory
sudo chown -R 1000:1000 /var/lib/zerobyte

Cannot Mount Remote Shares

Ensure your container has the necessary capabilities:

cap_add:
  - SYS_ADMIN
devices:
  - /dev/fuse:/dev/fuse

Logs

View detailed logs with:

# Follow logs in real-time
docker compose logs -f zerobyte

# View last 100 lines
docker compose logs --tail=100 zerobyte

# Enable debug logging
# Add to docker-compose.yml environment:
- LOG_LEVEL=debug

Next Steps

Now that Zerobyte is installed, proceed to the Quick Start guide to configure your first backup:

Quick Start Guide

Set up your first volume, repository, and backup job

Get Started

Core Concepts

Configuration

Guides

Advanced

Installation

Installation

Prerequisites

Basic Installation

1. Create docker-compose.yml

2. Configure Environment Variables

Required Environment Variables

Optional Environment Variables

3. Configure Volume Mounts

4. Start Zerobyte

5. Access the Web Interface

Simplified Installation (No Remote Mounts)

Mounting Local Directories

Advanced Configuration

Using Docker Secrets for Sensitive Data

Mounting rclone Configuration

Reverse Proxy Setup

Updating Zerobyte

Troubleshooting

Container Won’t Start

Permission Issues

Cannot Mount Remote Shares

Logs

Next Steps

Quick Start Guide

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Guides

Advanced

​Installation

​Prerequisites

​Basic Installation

​1. Create docker-compose.yml

​2. Configure Environment Variables

​Required Environment Variables

​Optional Environment Variables

​3. Configure Volume Mounts

​4. Start Zerobyte

​5. Access the Web Interface

​Simplified Installation (No Remote Mounts)

​Mounting Local Directories

​Advanced Configuration

​Using Docker Secrets for Sensitive Data

​Mounting rclone Configuration

​Reverse Proxy Setup

​Updating Zerobyte

​Troubleshooting

​Container Won’t Start

​Permission Issues

​Cannot Mount Remote Shares

​Logs

​Next Steps

Quick Start Guide

Build docs developers (and LLMs) love

Installation

Prerequisites

Basic Installation

1. Create docker-compose.yml

2. Configure Environment Variables

Required Environment Variables

Optional Environment Variables

3. Configure Volume Mounts

4. Start Zerobyte

5. Access the Web Interface

Simplified Installation (No Remote Mounts)

Mounting Local Directories

Advanced Configuration

Using Docker Secrets for Sensitive Data

Mounting rclone Configuration

Reverse Proxy Setup

Updating Zerobyte

Troubleshooting

Container Won’t Start

Permission Issues

Cannot Mount Remote Shares

Logs

Next Steps