Connect an S3 bucket

Atlas never bundles its own storage — every deployment points at an S3-compatible endpoint you already control. This walks through both common cases: a local MinIO for development, and real AWS S3 for production. See Database & Storage for the full variable reference this guide draws from.

Leave ATLAS_S3_ENDPOINT_URL unset entirely — the AWS SDK talks to real AWS by default. Leave ATLAS_AWS_ACCESS_KEY_ID and ATLAS_AWS_SECRET_ACCESS_KEY unset too, and let boto3’s own credential chain resolve one of:

an IAM role attached to the instance/task/pod running the API (the recommended path — no long-lived key sitting in .env at all),
~/.aws/credentials on the machine running the API,
the standard AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY environment variables.

Only set ATLAS_AWS_ACCESS_KEY_ID / ATLAS_AWS_SECRET_ACCESS_KEY directly if none of those apply. ATLAS_AWS_SESSION_TOKEN is only needed on top of those two for temporary credentials (STS / SSO / AssumeRole) — a plain IAM user key pair never needs it.

compose.yaml already runs one for you. Point Atlas at it and hand it MinIO’s own root credentials, which act as a full access key pair for a local, throwaway instance:

ATLAS_S3_ENDPOINT_URL=http://localhost:9000
ATLAS_AWS_ACCESS_KEY_ID=atlas          # MINIO_ROOT_USER in the repo root .env
ATLAS_AWS_SECRET_ACCESS_KEY=atlaslocal # MINIO_ROOT_PASSWORD, same file

The same two variables work unchanged against any other S3-compatible service (Ceph RGW, Backblaze B2, …) — only the endpoint and credentials change.

2. Set the staging bucket

tusd (resumable uploads) writes every upload into one fixed bucket before Atlas relays it into its real destination workspace — this bucket is never browsed directly, so it needs to exist but nothing else points at it:

ATLAS_S3_STAGING_BUCKET=atlas-staging

Against MinIO, create it once through the console at http://localhost:9001 (or mc mb local/atlas-staging); against real AWS, create it the same way you’d create any other bucket in your account (console, aws s3 mb, or your infrastructure-as-code of choice).

3. Restart and verify

Environment variables are read once at process start, so restart the API after editing .env. Then confirm the connection with a superuser session:

curl -b cookies.txt http://localhost:8000/api/v1/buckets

An empty or populated list back means Atlas reached the endpoint and listed buckets successfully; a connection error at this point almost always means ATLAS_S3_ENDPOINT_URL or the credentials are wrong, not anything deeper in Atlas itself.