> Index of every page on this site: [llms.txt](https://docs.a-line.cloud/llms.txt)

# Use object storage

> Create an S3-compatible bucket, make an access key and attach the bucket to an app.

**Goal**: a bucket for uploads, exports or backups, reachable with any S3
client, and an app that gets its credentials as environment variables.

## Before you start

- An organization with credit on its balance. Storage is billed per GiB.
- An S3 client, such as the `aws` CLI or `rclone`, if you want to test from
  your machine.

## Create a bucket

<Steps>
<Step>

Open **Object storage** in the sidebar and select **Create bucket**.

</Step>
<Step>

Enter a **Name**, such as `shop-uploads`.

</Step>
<Step>

Optional: a **Description** (what the bucket is for) and a **Quota** in
GiB, to limit how large the bucket can grow.

</Step>
<Step>

Select **Create bucket**.

</Step>
</Steps>

The bucket opens on its **Overview** tab. The **Connection** card shows the
**S3 API endpoint**, the **Region** and the **Bucket URL**. S3 clients use
the endpoint with path-style addressing.

## Make an access key

<Steps>
<Step>

Go to the **Access keys** tab. The **Create access key** dialog opens
when you add a key.

</Step>
<Step>

Optional: a **Name**, a **Path prefix** to limit the key to part of the
bucket, and an expiry in days.

</Step>
<Step>

Pick the **Permission**: **Read-only** to list and read objects, or
**Read & write** to also upload and delete.

</Step>
<Step>

Select **Create key**. The **Save your access key** dialog shows the **Access
key ID** and the **Secret access key**. Copy them, then confirm
**I have saved the secret**.

<Callout type="warn">
  The secret access key is shown only in this dialog. If you lose it, make a
  new key.
</Callout>

</Step>
</Steps>

The key only works for this bucket. The dialog also gives ready-made
snippets: **Env vars**, **aws CLI**, **rclone**, **AWS SDK** and **boto3**.

## Attach the bucket to an app

You do not need to copy keys into an app.

<Steps>
<Step>

Open the app on the project canvas and go to its **Env Vars** tab.

</Step>
<Step>

Select **Attach bucket** and pick the bucket.

</Step>
<Step>

Choose the credentials:
- **Shared key**: all pods use one key.
- **Per-pod keys (rotated automatically)**: each pod gets its own key.
  These are billed as dynamic leases.

</Step>
<Step>

Optional: a **Path prefix**, so the app only sees part of the bucket.

</Step>
<Step>

Deploy the app.

</Step>
</Steps>

The app gets these variables, with the prefix `S3` by default:

| Variable | Value |
| --- | --- |
| `S3_ENDPOINT` | The S3 API endpoint |
| `S3_REGION` | The region |
| `S3_BUCKET` | The bucket name |
| `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` | The credentials |
| `S3_FORCE_PATH_STYLE` | `true`; set your client to path-style addressing |
| `S3_URL`, `S3_PREFIX` | The bucket URL and the path prefix |

## Verify

With the **Env vars** snippet from the key dialog, list the bucket from your
machine. Copy the endpoint from the **Connection** card:

```bash
export S3_ENDPOINT=<S3 API endpoint>
export AWS_ACCESS_KEY_ID=AKEXAMPLE0000000000
export AWS_SECRET_ACCESS_KEY=example-secret-key
aws s3 ls s3://shop-uploads --endpoint-url "$S3_ENDPOINT"
```

Open the **Objects** tab to browse what the app wrote. The **Used by** tab
lists the apps the bucket is attached to.

## Troubleshooting

- **"The specified bucket does not exist"** or wrong-host errors: the client
  uses virtual-host addressing. Turn on path-style addressing.
- **Access denied**: the key is **Read-only**, has a **Path prefix** that
  does not cover the object, has expired, or belongs to another bucket.
- **Uploads fail once the bucket is full**: raise the quota on the
  **Settings** tab, or delete old objects.

## Public files

A bucket is private by default. **Make public** on the bucket serves its
objects to anyone with the URL; **Make private** turns it off again. The
**Domains** tab serves the bucket on your own host name.

## In IaC

A bucket is a file `buckets/<name>.yaml`. An app reaches it through
`storage_bindings`, with a `permission`, a `key_prefix`, an `env_prefix`
and a `credential_mode` of `static` or `per_pod`. See
[Buckets in IaC](/iac/buckets) and [bucket access](/iac/data#storage-bindings).

## Next steps

- [Volumes and backups](/guides/volumes-and-backups): backups go to your
  object storage.
- [Buckets in IaC](/iac/buckets)
- [Billing](/billing)
