Skip to main content

​
Storage backends

Qodex stores product state in Postgres and stores large artifacts in a blob backend. Artifacts include screenshots, videos, DOM snapshots, console logs, network logs, uploaded attachments, and large tool-call payloads. These files are important for debugging failed tests and reviewing findings.

​
Backend choices

Qodex chooses the backend at boot with:
or:
If unset, production defaults to s3 and development defaults to local.

​
Local storage

Local storage writes artifact files to disk. In the Docker image, the default state directory is /data, so artifacts land under:
Mount /data as a named volume or host directory:
Use local storage when the deployment is small and the host disk is backed up. Do not use an ephemeral container filesystem for production artifacts.

​
S3 storage

S3 storage is the recommended production backend. Set:
Qodex uses the normal AWS SDK credential chain. On ECS Fargate, the preferred setup is an IAM task role with permissions to put, get, and delete objects in the artifact bucket. Qodex uses presigned URLs for direct upload and download flows, so large files do not need to pass through the application server.

​
S3-compatible storage

For MinIO, Cloudflare R2, Backblaze B2, Wasabi, or another compatible service, set an endpoint and credentials:
The service must support SigV4 presigned URLs.

​
What Qodex stores

API-only runs usually write fewer artifacts. UI runs with video enabled can write much more.

​
Retention and lifecycle

Artifacts are often the evidence behind findings. If you expire them too early, the finding still exists but evidence links may no longer open. A reasonable starting point:
  • Keep recent screenshots and videos hot for 90 days.
  • Expire temporary attachment staging paths after 7 days.
  • Expire or archive logs after 180 days.
  • Move older high-volume artifacts to cheaper storage when supported.
Tune this based on how long your team needs to audit failures.

​
Moving from local to S3

There is no built-in migration command. To move existing artifacts:
  1. Stop Qodex.
  2. Sync the local blob directory to S3.
  3. Set STORAGE_BACKEND=s3 and the S3 variables.
  4. Start Qodex again.
Because artifact keys are stored in Postgres, keep the same key paths when syncing.

​
Next steps

Environment variables

See every storage-related variable.

Single-container deploy

Mount /data for local storage.

AWS Terraform reference

Review the production S3 layout.

Secret management

Understand what is encrypted separately from artifacts.