Provisioned Resources

Zerobyte can sync operator-managed repositories and volumes from a JSON configuration file at startup. This is useful when you want credentials and connection details to live in deployment-time configuration instead of being entered through the UI.

What Provisioning Supports Today

Provisioning currently supports:

• repositories
• volumes
• secret references through env:// and file://
• updating managed resources in place by keeping the same id
• deleting managed resources with "delete": true

Provisioning does not currently support:

• backup jobs or schedules
• notification destinations
• exporting UI-created resources back into provisioning JSON
• live reloading without restarting the Zerobyte container

Prerequisites

• A running Zerobyte instance with an organization ID
• The PROVISIONING_PATH environment variable pointing to your JSON file

Find your organization ID

1. Sign in to Zerobyte and switch to the organization you want to provision into
2. Open Settings
3. Open the Organization tab
4. Copy the read-only Organization ID value from Organization Details

Quick Start

{
	"version": 1,
	"repositories": [
		{
			"id": "local-repo",
			"organizationId": "your-organization-id",
			"name": "Primary Local Repository",
			"backend": "local",
			"compressionMode": "auto",
			"config": {
				"backend": "local",
				"path": "/var/lib/zerobyte/repositories/primary",
				"isExistingRepository": false
			}
		}
	],
	"volumes": [
		{
			"id": "documents",
			"organizationId": "your-organization-id",
			"name": "Documents",
			"backend": "directory",
			"autoRemount": true,
			"config": {
				"backend": "directory",
				"path": "/data/documents"
			}
		}
	]
}

services:
  zerobyte:
    image: ghcr.io/nicotsx/zerobyte:latest
    environment:
      - PROVISIONING_PATH=/config/provisioning.json
    volumes:
      - ./provisioning.json:/config/provisioning.json:ro
      - /var/lib/zerobyte:/var/lib/zerobyte
      - /srv/documents:/data/documents

docker compose up -d

Root File Format

The root object always has the same shape:

{
	"version": 1,
	"repositories": [],
	"volumes": []
}

Repository Entry Reference

Each item in repositories uses this top-level shape:

{
	"id": "repo-id",
	"organizationId": "org-id",
	"name": "Repository Name",
	"backend": "local",
	"compressionMode": "auto",
	"delete": false,
	"config": {
		"backend": "local",
		"path": "/var/lib/zerobyte/repositories/repo-id"
	}
}

Repository Shared Config Fields

These fields are available inside every repository config object:

Bandwidth limit objects use this shape:

{
	"enabled": true,
	"value": 10,
	"unit": "Mbps"
}

unit must be one of Kbps, Mbps, or Gbps.

Repository Backends

{
	"backend": "local",
	"path": "/var/lib/zerobyte/repositories/primary",
	"isExistingRepository": false
}

{
	"backend": "s3",
	"endpoint": "https://s3.amazonaws.com",
	"bucket": "company-backups",
	"accessKeyId": "env://AWS_ACCESS_KEY_ID",
	"secretAccessKey": "file://aws_secret_access_key",
	"isExistingRepository": true
}

{
	"backend": "r2",
	"endpoint": "https://<account-id>.r2.cloudflarestorage.com",
	"bucket": "zerobyte-backups",
	"accessKeyId": "env://R2_ACCESS_KEY_ID",
	"secretAccessKey": "env://R2_SECRET_ACCESS_KEY",
	"isExistingRepository": true
}

{
	"backend": "gcs",
	"bucket": "zerobyte-backups",
	"projectId": "my-gcp-project",
	"credentialsJson": "file://gcs_credentials_json",
	"isExistingRepository": true
}

{
	"backend": "azure",
	"container": "zerobyte-backups",
	"accountName": "storageaccount",
	"accountKey": "env://AZURE_STORAGE_ACCOUNT_KEY",
	"endpointSuffix": "core.windows.net",
	"isExistingRepository": true
}

{
	"backend": "rclone",
	"remote": "remote-name",
	"path": "zerobyte/backups",
	"isExistingRepository": true
}

{
	"backend": "rest",
	"url": "https://rest-server.example.com",
	"username": "env://REST_USERNAME",
	"password": "file://rest_password",
	"path": "zerobyte",
	"isExistingRepository": true
}

{
	"backend": "sftp",
	"host": "backup.example.com",
	"port": 22,
	"user": "backup",
	"path": "/srv/restic",
	"privateKey": "file://sftp_private_key",
	"skipHostKeyCheck": false,
	"knownHosts": "backup.example.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI..."
}

Volume Entry Reference

Each item in volumes uses this top-level shape:

{
	"id": "volume-id",
	"organizationId": "org-id",
	"name": "Volume Name",
	"backend": "directory",
	"autoRemount": true,
	"delete": false,
	"config": {
		"backend": "directory",
		"path": "/data/volume"
	}
}

Volume Backends

{
	"backend": "directory",
	"path": "/data/documents"
}

{
	"backend": "nfs",
	"server": "10.0.0.10",
	"exportPath": "/exports/media",
	"port": 2049,
	"version": "4.1",
	"readOnly": true
}

{
	"backend": "smb",
	"server": "fileserver.local",
	"share": "team",
	"username": "backup-user",
	"password": "env://SMB_PASSWORD",
	"vers": "3.0",
	"domain": "WORKGROUP",
	"port": 445,
	"readOnly": false
}

{
	"backend": "webdav",
	"server": "cloud.example.com",
	"path": "/team-a",
	"username": "team-a",
	"password": "env://WEBDAV_PASSWORD",
	"port": 443,
	"ssl": true
}

{
	"backend": "sftp",
	"host": "files.example.com",
	"port": 22,
	"username": "backup-user",
	"privateKey": "file://volume_sftp_private_key",
	"path": "/srv/data",
	"readOnly": true,
	"skipHostKeyCheck": false,
	"knownHosts": "files.example.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI..."
}

{
	"backend": "rclone",
	"remote": "remote-name",
	"path": "team-a",
	"readOnly": true
}

Secret References

Supported secret references use one of these prefixes:

Only specific fields are resolved as secret references. Other string fields are treated literally.

Repository fields that support secret references

• shared fields: customPassword, cacert
• s3: accessKeyId, secretAccessKey
• r2: accessKeyId, secretAccessKey
• gcs: credentialsJson
• azure: accountKey
• rest: username, password
• sftp: privateKey

Volume fields that support secret references

• smb: password
• webdav: password
• sftp: password, privateKey

Resolved secret values are encrypted before Zerobyte stores them in the database.

Rotating Secrets

To rotate a provisioned secret:

1. Update the environment variable or secret file
2. Restart Zerobyte with docker compose restart

Zerobyte re-resolves supported secret references on each startup.

Updating And Removing Managed Resources

• Keep the same id to update a managed resource in place
• Changing only name keeps the same underlying resource record
• Setting "delete": true removes the managed resource on the next startup sync

Deletion entries still need the normal entry shape today because the provisioning file is validated before Zerobyte applies the delete flag:

{
	"id": "repo-to-remove",
	"organizationId": "your-organization-id",
	"name": "Repo to remove",
	"backend": "local",
	"delete": true,
	"config": {
		"backend": "local",
		"path": "/var/lib/zerobyte/repositories/old",
		"isExistingRepository": true
	}
}

Troubleshooting

No matching discriminator

This error usually means one of these is wrong:

• backend is not a valid value for that resource type
• config.backend does not match the top-level backend
• the config object does not match the required fields for that backend

Secret reference errors

• env://NAME requires the environment variable to exist in the Zerobyte container
• file://name requires /run/secrets/name to exist
• Zerobyte stops syncing when it hits a provisioning error, so fix the first reported error and restart again

Important Notes

• Changes to provisioning.json only apply on container restart
• Provisioned resources appear in the normal UI and are marked as managed
• Editing a provisioned resource in the UI is useful for testing, but the next provisioning sync can overwrite it