Self-Host Zerobyte and Access It with Localtonet

What Zerobyte does and how this deployment works

Zerobyte is an open-source backup automation service built on Restic. Restic remains the underlying backup engine, while Zerobyte provides a web control plane for routine administration. Operators can connect source volumes, create backup repositories, define schedules and retention policies, monitor runs, browse snapshots, restore data, and perform repository maintenance without assembling separate scripts for every routine task.

Zerobyte supports local directories and remote sources such as NFS, SMB/CIFS, WebDAV, SFTP, and rclone-backed storage. Backup repositories can use local storage, S3-compatible services, Google Cloud Storage, Azure Blob Storage, REST servers, SFTP targets, and providers available through rclone. The exact source and destination settings depend on your storage systems, credentials, permissions, recovery objectives, and failure model.

Zerobyte runs as a Docker container. Its web interface and API listen on port 4096 by default. Docker Compose describes the image, port mapping, environment variables, capabilities, devices, and persistent volumes. The application data directory inside the container is /var/lib/zerobyte, and it must be mapped to durable local storage on the host.

Localtonet is a separate connectivity layer. Zerobyte continues running on your own server and remains responsible for its users, roles, sessions, and application authorization. Our client establishes an outbound connection from a device that can reach Zerobyte to a Localtonet relay server. A running HTTP tunnel then maps a public HTTPS address to the local Zerobyte HTTP endpoint. The endpoint is available only while the selected Localtonet client is connected and the tunnel is running.

Separate application state, source data, and repositories

Zerobyte's application directory is not the same resource as a source directory or backup repository. The application directory contains the configuration, database, and encryption-related material needed to operate Zerobyte. Source directories contain the files you want to protect. Repositories contain the Restic snapshots from which you recover.

Plan persistence, permissions, capacity, and disaster recovery for all three resources. Backing up only the application directory does not protect the source data, while preserving only the repository may leave an operator without the application configuration or credentials needed for a smooth recovery.

A working dashboard is also not proof that a backup is recoverable. A complete validation includes a successful backup run, snapshot inspection, repository health checks, and a restore to a safe destination. Remote access improves administrative reachability, but it cannot validate the integrity or usability of the stored data.

Prerequisites and deployment decisions

Zerobyte requires a server with Docker and Docker Compose. Docker Compose is included with Docker Desktop and may be installed separately as a plugin on Linux servers. This guide uses the modern docker compose command form. Consult the current Zerobyte installation documentation while preparing the host, especially if its requirements have changed since the evidenced v0.42 configuration.

You also need durable local storage for /var/lib/zerobyte, a valid timezone for scheduling, and a way to generate a random application secret. If you plan to back up host directories, identify their exact host paths before creating the Compose file. If Zerobyte must mount NFS, SMB, WebDAV, or SFTP sources from inside the container, use the standard installation and understand why it grants additional privileges.

Verify Docker and Docker Compose before continuing:

docker --version
docker compose version

Both commands should return version information. If either is unavailable, install the missing component using the instructions for your operating system and Docker distribution. There is no single verified package-manager command suitable for every supported host platform.

Choose the standard or simplified deployment

Prefer the simplified deployment when local bind-mounted directories meet your requirements. It removes capabilities that are unnecessary for that use case. If a network share is already mounted by the host operating system, you may expose that mounted path as a local bind mount, but you still need to evaluate ownership, permissions, ACL behavior, symlinks, and metadata fidelity.

Special persistence requirement for TrueNAS

Zerobyte's installation guidance notes that the host /var/lib path is ephemeral on TrueNAS and can be reset during system upgrades. Create a dedicated ZFS dataset and map that durable dataset to /var/lib/zerobyte inside the container. The documented example uses /mnt/tank/docker/zerobyte, but your pool and dataset path may differ.

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

Confirm that the dataset exists, remains persistent through upgrades, and is accessible to Docker before starting the container.

Install Zerobyte with Docker Compose

The documented installation sequence contains five stages: create the Compose configuration, set the environment variables, configure volume mounts, start the container, and access the web interface. Complete this local installation before creating a public tunnel. That boundary makes it easier to determine whether an error belongs to Zerobyte, Docker, host storage, local networking, or Localtonet.

Standard Compose configuration for remote mounts

The following example follows the documented v0.42 standard deployment while binding the host port to loopback for this tutorial. Replace the timezone and secret before starting it.

services:
  zerobyte:
    image: ghcr.io/nicotsx/zerobyte:v0.42
    container_name: zerobyte
    restart: unless-stopped
    cap_add:
      - SYS_ADMIN
    ports:
      - "127.0.0.1:4096:4096"
    devices:
      - /dev/fuse:/dev/fuse
    environment:
      - TZ=Europe/Zurich
      - BASE_URL=http://localhost:4096
      - APP_SECRET=REPLACE_WITH_YOUR_GENERATED_SECRET
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /var/lib/zerobyte:/var/lib/zerobyte

Generate the required secret with:

openssl rand -hex 32

Copy the output into APP_SECRET. Zerobyte requires a random value of at least 32 characters and uses it to encrypt sensitive data in its database. Do not paste it into tickets, screenshots, public repositories, or published shell transcripts.

Simplified Compose configuration for local directories

If every source is a local directory mounted into the container, remove SYS_ADMIN and /dev/fuse. This example maps one host directory to /mydata as read-only:

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

Replace /path/to/your/directory with a real host path. Inside Zerobyte, the source is available as /mydata, not under its original host path. Add other explicit mappings as needed, but do not map the entire host filesystem merely for convenience.

A read-only source reduces write access when Zerobyte only needs to create backups. It also prevents restoration to that source location. Use a separate writable restore destination for routine recovery testing.

Understand the important environment variables

The current Zerobyte documentation should remain your final reference for version-specific configuration. The following options are established by the supplied installation and configuration evidence:

Use an HTTP or IP-based BASE_URL for the initial local check. Zerobyte disables secure cookies for HTTP or IP-address access so local setup can work. An HTTPS domain enables secure cookies. When the final Localtonet public HTTPS address is known, update BASE_URL to that exact origin and recreate the container.

Do not enable TRUST_PROXY automatically merely because a tunnel exists. Its documented purpose is to trust an existing X-Forwarded-For header from a reverse proxy. Leave the default in place unless you have verified the full request path and have a specific reason to trust that header.

Start the service

docker compose up -d
docker compose ps

If the container does not remain running, inspect its logs:

docker compose logs -f zerobyte

Stop following the output after collecting the information you need. Before sharing logs, check them for private paths, repository addresses, account information, hostnames, or credentials.

Complete first-run setup and create a backup workflow

Open http://localhost:4096 on the Docker host when using the loopback mapping. Zerobyte prompts you to create an administrator account on first access. This account has full backup-management access, so use unique credentials and store them safely. There is no universal default username or password in this workflow.

Zerobyte organizes the initial backup lifecycle around four practical stages: connect a source volume, create a repository, define a backup job, and monitor or restore snapshots. Storage-specific form fields vary, so enter values issued by your own storage systems rather than copying generic credentials.

1. Connect a source volume

For a local bind mount, use the container-side path from compose.yaml, such as /mydata or /photos. A path that exists only on the host is not visible inside the container unless it is explicitly mounted.

For NFS, SMB, WebDAV, or SFTP mounting inside Zerobyte, use the standard deployment with SYS_ADMIN and /dev/fuse. Remote mounts can expose translated ownership, permissions, and ACL metadata. If metadata fidelity matters, test representative files, ownership, permissions, symlinks, and ACLs through an actual restore.

2. Create a backup repository

The repository stores encrypted Restic snapshots. Zerobyte supports local repositories and remote destinations including S3-compatible storage, Google Cloud Storage, Azure Blob Storage, REST servers, SFTP, and rclone-backed providers. Select a destination that matches your failure model. A repository on the same disk as the source cannot protect against failure or loss of that disk.

Preserve the credentials, recovery keys, and other information required to access snapshots independently of the live container. A repository that exists but cannot be authenticated to or decrypted is not recoverable.

3. Define the backup job

Connect the chosen volume and repository, then select a schedule appropriate for how quickly the source changes and how much data loss you can tolerate. Zerobyte supports cron-based scheduling, include and exclude rules, manual runs, compression choices, and retention policies.

Confirm that TZ represents the intended timezone. A syntactically correct job can run at the wrong local time when the container timezone is wrong. Retention should reflect both recovery requirements and available capacity. Observe actual repository growth before aggressively removing older recovery points.

4. Run, inspect, and restore

Trigger an initial backup and monitor its status. After completion, inspect the snapshot and verify that expected paths are present. Restore representative files and directories to a separate destination, open the restored content, and compare it with the source.

This test exercises repository access, decryption, snapshot traversal, write permissions, and the recovery procedure. It provides stronger evidence than a successful status indicator alone.

Verify Zerobyte locally before exposing it

Local verification creates a clean troubleshooting boundary. A tunnel cannot repair a stopped container, invalid environment variable, inaccessible mount, repository error, or host permission problem.

Check container state and logs:

docker compose ps
docker compose logs -f zerobyte

Look for missing variables, invalid filesystem paths, permission failures, mount errors, or repeated restarts. Correct the underlying setting in compose.yaml, recreate the container when required, and check again.

With the loopback binding, open:

http://localhost:4096

The browser must run on the Docker host because localhost always refers to the machine making the request. A successful check displays the Zerobyte interface. Complete administrator setup, sign in, and confirm that configured source paths are visible from the container's perspective.

If you deliberately used the upstream-style 4096:4096 mapping rather than loopback, the local network address takes this form:

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

Use that form only on an appropriately protected network where the server is reachable. Do not create an internet-facing router port forward for this tutorial.

Local readiness checklist

• Docker and Docker Compose return valid version information.
• The Zerobyte container remains running.
• Logs contain no unresolved startup, mount, or storage errors.
• The interface loads at the address configured in BASE_URL.
• The administrator account has unique credentials.
• /var/lib/zerobyte maps to durable local host storage.
• Expected source paths are visible inside the container.
• An initial job creates a snapshot in the intended repository.
• The snapshot contains the expected files.
• A test restore succeeds to a safe destination.

Access Zerobyte remotely with a Localtonet HTTP tunnel

Once local access works, an HTTP tunnel can publish the web interface through Localtonet. Our client runs on the Zerobyte host or another device that can reach it. The client establishes an outbound connection to a selected relay server, and the running tunnel provides a public HTTPS address.

Review the current Localtonet HTTP tunnel documentation before configuration. Available relay servers, regions, process types, and account-specific choices must come from the current dashboard. Do not copy a server code, hostname, or region from another deployment.

An HTTP tunnel targets only the local IP address and port you configure. If the client and Zerobyte run on the same host, use 127.0.0.1 and port 4096. If they run on different devices, use an address reachable from the Localtonet client and protect that private network path appropriately.

Create and start the HTTP tunnel

The current verified workflow preserves an important lifecycle distinction: creating a tunnel does not start it. Follow the dashboard and documentation in this order:

HTTP tunnels may use Random Sub Domain, Custom Sub Domain, or Custom Domain process types, with each serving the same target content through a public HTTPS address. Exact custom-domain DNS instructions can change and should be taken from current Localtonet documentation rather than inferred from this tutorial.

Update Zerobyte's public base URL

Replace the initial local BASE_URL with the exact assigned HTTPS origin. Do not copy this placeholder literally:

environment:
  - TZ=Europe/Zurich
  - BASE_URL=https://YOUR_ASSIGNED_PUBLIC_HOST
  - APP_SECRET=REPLACE_WITH_YOUR_EXISTING_GENERATED_SECRET

Keep your existing application secret. Changing the public origin does not require rotating APP_SECRET. Recreate the service:

docker compose down
docker compose up -d
docker compose ps

Test the assigned address only after the container is running again. If the page loads but authentication loops, browser requests fail CORS checks, or navigation returns to the wrong address, compare BASE_URL with the exact public scheme and hostname.

Routine operation, security, and recovery

Use least privilege for storage

Mount only the directories Zerobyte needs. Use :ro when a source should not be modified, then restore to a separate writable destination. If remote mount support is unnecessary, use the simplified deployment rather than retaining SYS_ADMIN and /dev/fuse.

Protect compose.yaml because it may contain APP_SECRET and sensitive deployment paths. Zerobyte supports APP_SECRET_FILE as an alternative, and it is mutually exclusive with APP_SECRET. Secret-file mounting and permissions depend on your container environment, so verify them before switching.

Limit and review remote reachability

Keep the Docker mapping on loopback when the Localtonet client runs on the same host. Start the tunnel only for the periods when remote administration is needed if continuous exposure is unnecessary. Stopping the tunnel does not stop scheduled local backups, provided the Zerobyte container and its storage remain available.

Treat the public URL, application login, and any tunnel-layer restriction as separate controls. The URL provides reachability. Zerobyte credentials provide application authentication. Any additional Localtonet access restriction must be verified against current documentation and configured deliberately. Do not infer such a restriction from HTTPS alone.

Monitor application and backup outcomes

Use docker compose ps for container state and docker compose logs -f zerobyte during investigation. Inside Zerobyte, review run status, next-run timing, snapshot history, repository health, and notification outcomes. Test notification delivery rather than assuming that a saved configuration works.

A useful operating routine includes investigating failures, reviewing unexpectedly short or long jobs, checking repository growth, confirming retention results, resolving stale locks carefully, and restoring representative data on a recurring schedule.

Control backup CPU use

If Restic processes create excessive CPU pressure, Zerobyte supports GOMAXPROCS:

environment:
  - GOMAXPROCS=2

Restart the container after changing it. The value applies to Restic processes started after the restart and does not alter operations already running. Select a positive integer based on your host rather than assuming that 2 is ideal everywhere.

Repository compression also affects CPU use. Zerobyte supports off, auto, and max compression behavior through Restic. Turning compression off can reduce CPU consumption, auto provides the usual balance, and max may save more storage at the cost of additional CPU work. Measure with your own data and hardware.

Plan upgrades and server-loss recovery

Preserve the application data directory, but do not confuse it with the backup repository. Record repository locations, authentication requirements, recovery keys, and the procedure an operator would follow if the Zerobyte server disappeared.

Before changing a 0.x image tag, review the project's current releases, identify migration or configuration changes, confirm that persistent storage is healthy, and record the currently deployed tag. The v0.42 configuration in this guide is tied to the supplied evidence. Validate a newer version against its own documentation before adopting it.

Troubleshooting Zerobyte and Localtonet access

Zerobyte maintains a dedicated troubleshooting guide. Use it for current project-specific behavior while following the layered checks below.

The container exits or repeatedly restarts

Run docker compose ps and docker compose logs -f zerobyte. Confirm that BASE_URL and either APP_SECRET or APP_SECRET_FILE are configured correctly. Check YAML indentation, the application-data path, host permissions, and configured devices.

If using the standard deployment, confirm that /dev/fuse exists and can be passed to the container. If internal remote mounts are unnecessary, switch to the simplified configuration rather than forcing unsupported capabilities onto the host.

The browser cannot open localhost:4096

Confirm that the browser runs on the Docker host. Typing localhost on another computer points to that other computer. Then verify that the container is running and that Compose maps 127.0.0.1:4096 to container port 4096.

If you changed the internal PORT, update the Docker mapping and Localtonet target consistently.

A local source directory is missing

Check the bind mount in compose.yaml. For /path/to/photos:/photos:ro, Zerobyte must use /photos. It cannot access the original host path unless that path is deliberately mounted into the container.

After changing mounts, recreate the container:

docker compose down
docker compose up -d

A backup receives permission errors

Check host ownership, permissions, ACLs, and the bind mount's access mode. A read-only source supports backup reads but cannot receive an in-place restore. Network filesystems may present translated metadata, so reproduce the issue from the container's view and test representative files.

The Localtonet public URL does not load

First verify Zerobyte locally. Then confirm that the Localtonet client is connected, the correct device token is selected, and the tunnel has been started rather than merely created. Confirm that the configured target is reachable from the device running our client.

For a same-host deployment, target 127.0.0.1:4096. If the client runs elsewhere, its own 127.0.0.1 cannot reach Zerobyte. Use a protected address reachable from that client and ensure Docker listens on the required interface.

The public page loads but sign-in or browser requests fail

Compare BASE_URL with the exact public HTTPS origin. Recreate the container after changing it. Do not add speculative TRUSTED_ORIGINS values or enable TRUST_PROXY without identifying the specific CORS or forwarded-header problem being solved.

Schedules run at the wrong time

Check TZ. Zerobyte identifies timezone configuration as important for accurate scheduling. Set a valid timezone or use UTC, restart the container, and review the next scheduled run.

Backups use too much CPU

Consider a positive GOMAXPROCS limit and restart the container. Review repository compression as well. Change one factor at a time so its effect can be measured.

The tunnel works, but the security model is unclear

Stop the tunnel while you review the deployment. Confirm which controls exist at the Zerobyte application layer and which, if any, are documented at the tunnel layer. The supplied evidence confirms Zerobyte authentication and a public Localtonet endpoint, but it does not establish tunnel-layer authentication for this workflow. Do not continue under the assumption that an obscure URL is private.

Frequently asked questions