Docker

Docker

The repository's Dockerfile includes the Python command and runtime tools, including ExifTool for create --order-by content-date. Archive creation with a fixed capacity is the simplest container workflow; physical drives and ISO mounting need additional host integration.

Use the prebuilt image

Download the published image; no source checkout or local Python installation is needed:

docker pull ghcr.io/xitee1/bd-archiver:latest
docker run --rm ghcr.io/xitee1/bd-archiver:latest --version
docker run --rm ghcr.io/xitee1/bd-archiver:latest --help

The release workflow publishes linux/amd64 and linux/arm64 images when v*.*.* tags are pushed. latest tracks the latest published release; it can lag behind the current checkout. Check --version and --help before assuming it supports the current source's options. See the package page for version tags.

The examples below use a locally built image named bd-archiver:local. To use the prebuilt release instead, replace that image name with ghcr.io/xitee1/bd-archiver:latest; the volume and device setup is the same.

Build the current checkout

To use the same code as your checkout:

docker build -t bd-archiver:local .
docker run --rm bd-archiver:local --help

The local build uses the version label 0.0.0+docker-local unless BD_ARCHIVE_VERSION is supplied as a build argument. This does not change the code being built.

The Dockerfile compiles the burn-timeout helper in a separate build stage and installs the platform wheel in the runtime image. The final image needs no C compiler, and no additional host library or timeout setting is required. The same burn --write-timeout SECONDS option and default of 180 seconds apply, as do burn --buffer SIZE and its 512 MiB default; the container needs that much free memory for the ring buffer. Normal drive-access and mounting requirements below still apply.

Prepare archives without a drive

Create /data/out on the host first. Mount the source read-only and output writable:

docker run --rm -it \
  -v /data/photos:/source/photos:ro \
  -v /data/out:/output \
  bd-archiver:local \
  create -m dar -s /source/photos -n Photos -o /output -b 25025314816

The capacity is an example; use a byte count suitable for your media. The result is a portable discs/ tree (raw: disc/ and manifest.json); add --iso to create images instead. Folder output can be verified, restored and burned on the host after creation in the container. For raw mode, see the next section.

The default container runs as root, so generated host files may be root-owned. Choose container user settings appropriate for your host directories. Running with another UID also requires any relevant drive/mount permissions.

Raw discs from an incoming collection

Raw create asks interactively for the plan, the confirmation and whether to remove the archived units from the source; run the container with -it. Mount a common parent for source and output: on the same host filesystem, create builds the disc from reflinks or hardlinks, while separate bind mounts can force copies even when the underlying device is the same. Removing archived units requires a writable source.

docker run --rm -it -v /data:/data bd-archiver:local \
  create -s /data/incoming -n Photos-2026-10 -o /data/out/photos-2026-10 \
  -b 25025314816 --max-free 5

It does not need optical devices with -b. With -y, the most ordered plan is selected and the source is never changed. See Raw data discs and Planning raw discs.

Drives and mounting

Auto-detection is not explicitly disabled in the code. It depends on the container's visible /sys/block/sr* entries and device nodes, which vary with runtime configuration. Pass an explicit -D /dev/sr0 whenever using a drive.

Passing only /dev/sr0 is not enough for every workflow. Burning uses raw SCSI ioctls and may need the associated /dev/sg* node and additional permissions. Physical-disc mounting also requires mount permissions or a working udisks2 service. Merely adding SYS_RAWIO is not a complete recipe for post-burn mounts.

A broad-access example for a trusted local image is:

docker run --rm -it --privileged --device=/dev/sr0 \
  -v /data/out:/output:ro \
  bd-archiver:local burn -i /output -D /dev/sr0

--privileged grants extensive host access. Use it only when that access is appropriate; a more narrowly configured runtime must account for the drive, SCSI device and verification mount requirements. For routine use, running burn and restore on the host avoids this container setup.

ISO verification and restoration

verify image.iso, extract -i with ISO files, and create --pack-with with an ISO call udisksctl for loop mounting. The image installs udisks2, but does not start a D-Bus/udisks2 service. Those workflows therefore do not work simply by launching this image, even if no physical drive is needed. Run them on the host with working udisks2.

For verification only, you can instead mount the ISO read-only on the host and pass that mounted directory into the container:

docker run --rm -it \
  -v /mnt/archive-disc:/disc:ro \
  bd-archiver:local verify /disc

Prepared disc folders and mounted DAR directories can be passed directly to extract -i without udisks2. Folder-based verification, restoration and packing therefore work without container mount services. Mount the input read-only and a separate restore/output directory writable.

For RAM staging, see Storage and layout. A small container tmpfs sized for one slice cannot hold a multi-disc restore's accumulated slices.