# S3

If you want to use S3 storage for the sccache cache, you need to set the following environment variables:

- `SCCACHE_BUCKET` with the name of the S3 bucket to use;
- `SCCACHE_REGION` with the S3 region. If you have set `SCCACHE_ENDPOINT`, you can set `SCCACHE_REGION` to `auto`;
- Optionally, `SCCACHE_ENDPOINT=<ip>:<port>` with a custom URL of a server you want a use, such as MinIO or DigitalOcean storage.
- `SCCACHE_S3_ENABLE_VIRTUAL_HOST_STYLE` to `true` if you are using a custom endpoint that supports virtual host style addressing. This is required for S3 transfer acceleration and some S3-compatible storage services. If you are using AWS S3, you can leave this unset.

If your endpoint requires HTTPS/TLS, set `SCCACHE_S3_USE_SSL=true`. If you don't need a secure network layer, HTTP (`SCCACHE_S3_USE_SSL=false`) might be better for performance.

Server-side encryption can be enabled in one of three modes. They are resolved in the following order of precedence:

- **SSE-KMS with a customer-managed KMS key:** set `SCCACHE_S3_SERVER_SIDE_ENCRYPTION_KMS_KEY_ID` to the KMS key ID/ARN. This implies `aws:kms` and takes precedence over the other settings.
- **SSE-KMS with the AWS-managed KMS key (`aws/s3`):** set `SCCACHE_S3_SERVER_SIDE_ENCRYPTION_AWS_KMS=true`.
- **SSE-S3 with an S3-managed key (AES256):** set `SCCACHE_S3_SERVER_SIDE_ENCRYPTION=true`.

More details about encryption [here](https://opendal.apache.org/docs/services/s3/#server-side-encryption) and documentation [here](https://docs.rs/opendal/latest/opendal/services/struct.S3.html#method.server_side_encryption_with_s3_key).

You can also define a prefix that will be prepended to the keys of all cache objects created and read within the S3 bucket, effectively creating a scope. To do that use the `SCCACHE_S3_KEY_PREFIX` environment variable. This can be useful when sharing a bucket with another application.

The `SCCACHE_S3_RW_MODE` environment variable can be set to `READ_ONLY` to make sccache use this backend in read-only mode. The default is `READ_WRITE`.

# R2

Cloudflare R2 is an S3-compatible object storage and works with the same configuration options as above. To use R2, you **must** define `SCCACHE_ENDPOINT`, otherwise sccache will default to AWS as the endpoint to hit. R2 also requires endpoint connections to be secure, therefore `https://` either needs to be included in `SCCACHE_ENDPOINT` or `SCCACHE_S3_USE_SSL=true` can be used, if the protocol is omitted. There are no regions in R2, so `SCCACHE_REGION` must point to `auto`. The below environment variables are recommended.

- `SCCACHE_BUCKET` is the name of your R2 bucket.
- `SCCACHE_ENDPOINT` should follow the format of `https://<ACCOUNT_ID>.r2.cloudflarestorage.com`. It is recommended that `https://` be included in this env var. Your account ID can be found [here](https://developers.cloudflare.com/fundamentals/get-started/basic-tasks/find-account-and-zone-ids/).
- `SCCACHE_REGION` should be set to `auto`.

## Credentials

Sccache is able to load credentials from various sources. Including:

- Static: `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`.
- Profile: `~/.aws/credentials` and `~/.aws/config`. The AWS_PROFILE environment variable can be used to select a specific profile if multiple profiles are available.
- EC2 Metadata Services: Via [IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html).
- AssumeRole: assume role with the role specified by `AWS_ROLE_ARN`.
- AssumeRoleWithWebIdentity: assume role with web webIdentity specified by `AWS_ROLE_ARN` and `AWS_WEB_IDENTITY_TOKEN_FILE`.

Alternatively, the `SCCACHE_S3_NO_CREDENTIALS` environment variable can be set to use public readonly access to the S3 bucket, without the need for credentials. Valid values for this environment variable are `true`, `1`, `false`, and `0`. This can be useful for implementing a readonly cache for pull requests, which typically cannot be given access to credentials for security reasons.
