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.
Choose a driver
Section titled “Choose a driver”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_DRIVERfs for local disk.
STORAGE_PATHThe directory. In the compose file it's the files Docker volume.
AWS S3, Cloudflare R2, Backblaze B2, MinIO or LocalStack.
STORAGE_DRIVERs3 for any S3-compatible service.
S3_BUCKETThe bucket. Required with the s3 driver.
S3_REGIONThe bucket's region.
S3_ENDPOINTA custom endpoint for R2, B2, MinIO or LocalStack, such as https://<account>.r2.cloudflarestorage.com. Leave it empty for AWS.
S3_FORCE_PATH_STYLEPath-style addressing, which MinIO and LocalStack need.
S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEYSet both, or neither to use the AWS credential chain (an IAM role is best on AWS).
S3_CONNECT_TIMEOUT_SECONDS, S3_REQUEST_TIMEOUT_SECONDSSeconds. The first is how long to wait for a connection before giving up. The second is how long a request may sit idle with no data moving, not how long it may take in total, so large files keep flowing.
The storage driver is read-only in Instance settings: it names STORAGE_DRIVER and is changed there, with a restart.
How an upload travels
Section titled “How an upload travels”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.
MinIO and LocalStack for development
Section titled “MinIO and LocalStack for development”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.
Moving between storages
Section titled “Moving between storages”# local disk to S3circi admin storage migrate --to s3 --bucket circi --region eu-west-1# S3 (or anything) to a directorycirci admin storage migrate --to fs --path /mnt/filesIt 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.
What is using space
Section titled “What is using space”Files and bytes by kind, and what is waiting to be deleted:
circi admin storage usageCheck that storage works
Section titled “Check that storage works”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.