Skip to content

Configure

Storage

Local disk, S3-compatible buckets, LocalStack and MinIO, and moving between them.

CirCI stores screenshots, diff images, thumbnails and hosted sites as files. Each file is named by its SHA-256 hash and checked when it's written, so an unchanged screenshot is uploaded and stored once, however many builds contain it. Storage grows with changes, not builds.

The default and the cheapest. Uploads go through the API, which writes each file to a temporary location while hashing it and moves it into place only if the hash matches. Back up the volume together with the database: Backups.

STORAGE_DRIVERDefault fs

fs for local disk.

STORAGE_PATHpathDefault /var/lib/circi/files

The directory. In the compose file it's the files Docker volume.

The storage driver is read-only in Instance settings: it names STORAGE_DRIVER and is changed there, with a restart.

How an upload reaches storage with each driverWith local disk the CLI sends each file to the CirCI API, which verifies the SHA-256 and writes it to the disk. With S3 the CLI asks CirCI for presigned URLs, uploads straight to the bucket with the checksum bound to the request, and finalize confirms each object.circi uploadin CICirCI APIhashes, verifiesDiskfs driverPUT /v1/filescirci uploadin CIBuckets3 driverpresigned PUT, bound to the SHA-256

With S3 the CLI uploads directly to the bucket through presigned URLs bound to the file's SHA-256 checksum (the x-amz-checksum-sha256 header, supported by AWS S3, R2 and MinIO), so storage rejects bytes that don't match, and finalize then confirms each object. The bucket must be reachable from where CI runs.

docker-compose.s3.yml adds a local MinIO (API on 9000, console on 9001) with a circi bucket and points the app at it. The end-to-end suite uses LocalStack for S3. Neither is meant for production.

Terminal window
# local disk to S3
circi admin storage migrate --to s3 --bucket circi --region eu-west-1
# S3 (or anything) to a directory
circi admin storage migrate --to fs --path /mnt/files

It copies every stored file to the new storage under the same keys and reports the Copied, already there, missing at the source and failed counts. It exits 1 if any copy failed. When it succeeds it tells you to set STORAGE_DRIVER (and its settings) and restart. Other options: --endpoint, --force-path-style.

Files and bytes by kind, and what is waiting to be deleted:

Terminal window
circi admin storage usage

circi admin doctor checks that the storage is usable and, for local disk, the free space. Instance › Health shows the same, and GET /readyz includes storage.