mirror of
https://github.com/nicotsx/zerobyte.git
synced 2026-06-03 13:37:22 -04:00
70c7de1efc
* feat(config): add support for APP_SECRET as a file * fix(tsc): ensure appSecret is set in type system * fix: pr feedback
89 lines
3.5 KiB
Markdown
89 lines
3.5 KiB
Markdown
# Provisioned repositories and volumes
|
|
|
|
This example shows how to keep operator-managed repositories and volumes in a mounted JSON file instead of creating them through the UI.
|
|
|
|
At startup, Zerobyte reads the provisioning file, resolves any `env://...` or `file://...` references, encrypts the resolved secrets into the database, and syncs the resources into the normal repositories and volumes lists as managed entries.
|
|
|
|
## Why this model
|
|
|
|
- Secret references stay in deployment-time config instead of the UI.
|
|
- Provisioned repositories and volumes show up in the normal UI and API.
|
|
- Secret rotation is just an env/secret update plus a restart.
|
|
|
|
## What this example includes
|
|
|
|
- `docker-compose.yml` mounts a provisioning file and a Docker secret.
|
|
- `.env.example` provides the environment variables used by `env://...` references.
|
|
- `provisioning.example.json` provisions one S3 repository and one WebDAV volume.
|
|
- `secrets/aws_secret_access_key.example` shows the file consumed by `file://aws_secret_access_key`.
|
|
|
|
## Prerequisites
|
|
|
|
- Docker + Docker Compose
|
|
- An existing Zerobyte organization ID (found in the UI under Settings > Organization)
|
|
- An S3-compatible repository target and a WebDAV share, or your own equivalent values
|
|
|
|
If this is a brand-new Zerobyte instance, finish first-run setup first so you have a real organization ID, then enable provisioning and restart the container.
|
|
|
|
## Setup
|
|
|
|
1. Copy the example files:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
cp provisioning.example.json provisioning.json
|
|
cp secrets/aws_secret_access_key.example secrets/aws_secret_access_key
|
|
```
|
|
|
|
2. Edit `.env`:
|
|
|
|
- Set `APP_SECRET` to a real secret, for example `openssl rand -hex 32`, or set `APP_SECRET_FILE` to a mounted secret file
|
|
- Set `ZEROBYTE_AWS_ACCESS_KEY_ID`
|
|
- Set `ZEROBYTE_WEBDAV_PASSWORD`
|
|
- Adjust `BASE_URL` and `TZ` if needed
|
|
|
|
3. Edit `provisioning.json`:
|
|
|
|
- Replace `organizationId` with your existing Zerobyte organization ID
|
|
- Update the S3 endpoint/bucket values
|
|
- Update the WebDAV server, path, and username
|
|
|
|
4. Edit `secrets/aws_secret_access_key` and replace the placeholder value with the real secret access key.
|
|
|
|
5. Start the stack:
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
## How secret references work
|
|
|
|
- `env://ZEROBYTE_AWS_ACCESS_KEY_ID` reads from a container environment variable.
|
|
- `env://ZEROBYTE_WEBDAV_PASSWORD` reads from a container environment variable.
|
|
- `file://aws_secret_access_key` reads `/run/secrets/aws_secret_access_key` inside the container.
|
|
- The resolved values are encrypted before Zerobyte stores them in the database.
|
|
|
|
`file://...` references are always resolved from `/run/secrets` and must be a single filename, not a nested path.
|
|
|
|
## Access
|
|
|
|
- UI/API: `http://<host>:4096`
|
|
|
|
## What you'll see in Zerobyte
|
|
|
|
- `AWS Production Backups` appears in the repositories list as a managed repository.
|
|
- `Team A WebDAV` appears in the volumes list as a managed volume.
|
|
- Changes to `provisioning.json`, `.env`, or mounted secret files apply on the next container restart.
|
|
|
|
## Rotating or removing provisioned resources
|
|
|
|
- Rotate an env-based secret: update `.env`, then restart Zerobyte.
|
|
- Rotate a file-based secret: update `secrets/aws_secret_access_key`, then restart Zerobyte.
|
|
- Remove a resource: add `delete: true`, then restart Zerobyte.
|
|
|
|
## Notes
|
|
|
|
- This example keeps `SYS_ADMIN` and `/dev/fuse` enabled because the sample volume uses WebDAV.
|
|
- Each provisioned entry must reference an existing `organizationId`.
|
|
- Each entry includes both a top-level `backend` and the matching `config.backend`.
|