# Get started with Object Storage

Create a bucket, create an access key for it, upload and list a file with the AWS CLI, and delete everything again, in about ten minutes.

Replace _example-uploads_ with a bucket name of your own: names are shared by everyone on the
platform, so start it with your company or project.

## Prerequisites

- Permission for `s3:CreateBucket`, `s3:PutObject`, `s3:ListObjects`, `s3:ListBucketVersions`,
  `s3:DeleteObjectVersion` and `s3:DeleteBucket`, and `iam:CreateAccessKey` and
  `iam:DeleteAccessKey`.
- The AWS CLI on your computer. For the CLI steps, the dcloud CLI, signed in.

## Step 1: Create a bucket

**Console**
1. Open **Object Storage**, then choose **Create bucket**.
2. For **Name**, enter example-uploads.
3. Choose **Create**.

The bucket's page opens. Its **Address** is `https://example-uploads.s3.<domain>`.

**CLI**
```sh
dcloud s3 buckets create --name example-uploads
```

**API**
```http
POST /s3/api/buckets
{ "name": "example-uploads" }
```

**Terraform**
```hcl
resource "dcloud_bucket" "uploads" {
  name = "example-uploads"
}
```

The bucket is in `de1a` (Falkenstein), private, and encrypted with the platform key.

## Step 2: Create an access key for the bucket

**Console**
1. On the bucket's page, choose **Create access key**. The sheet opens with **Limited to** set to
   **One bucket** and **Access** set to **Read and write**.
2. Choose **Create access key**.
3. Copy the lines under **AWS CLI profile** and run them in a terminal. They set up the profile
   `dcloud` with the key, region `de1` and the endpoint. This is the only time the secret is
   shown.

**CLI**
```sh
dcloud iam access-keys create --description "getting started" --scope-policy '{"Version":"2024-01-01","Statement":[{"Effect":"Allow","Action":["s3:ListObjects","s3:GetObject","s3:PutObject","s3:DeleteObject"],"Resource":["rn:ews::org-EXAMPLE1234:s3:bucket/example-uploads","rn:ews::org-EXAMPLE1234:s3:bucket/example-uploads/object/*"]}]}'
```

Replace _org-EXAMPLE1234_ with your organization's id. Set up a profile with the key's
`accessKeyId` and `secretKey` (see [Use the AWS CLI](use-the-aws-cli.md)).

**API**
```http
POST /iam/api/access-keys
{ "description": "getting started" }
```

Set up a profile with the key's `accessKeyId` and `secretKey` (see
[Use the AWS CLI](use-the-aws-cli.md)).

**Terraform**
```hcl
resource "dcloud_iam_access_key" "getting_started" {
  description = "getting started"
}
```

## Step 3: Upload and list a file

```sh
echo hello > hello.txt
aws --profile dcloud s3 cp ./hello.txt s3://example-uploads/hello.txt
aws --profile dcloud s3 ls s3://example-uploads/
```

The listing shows `hello.txt`. In the console, the bucket's **Objects** tab shows it too.

## Clean up

You pay for what the bucket stores until you delete it.

**Console**
1. On the bucket's page, in the **⋯** menu, choose **Empty bucket**, enter the bucket's name and
   confirm.
2. When the banner says the bucket is emptied, choose **Delete bucket** in the **⋯** menu, enter the
   bucket's name and choose **Delete bucket**.
3. Open **Identity** → **Access keys** and delete the key: **Delete key** in its menu, then
   **Delete**.

**CLI**
```sh
dcloud s3 bucket-objects empty example-uploads
dcloud s3 bucket-objects empty-status example-uploads
```

Emptying runs in the background: repeat `empty-status` until its `status` is `done`, then delete
the bucket. Before that, the delete is refused with `409` (the bucket is not empty).

```sh
dcloud s3 buckets delete example-uploads
```

Then `dcloud iam access-keys delete` with the key's id.

**API**
```http
POST /s3/api/buckets/example-uploads/empty
```

When `GET /s3/api/buckets/example-uploads/empty` says `done`, call
`DELETE /s3/api/buckets/example-uploads`, then `DELETE /iam/api/access-keys/<id>`.

**Terraform**
`terraform destroy` removes the key and the bucket; empty the bucket first, since a bucket that
holds objects is not deleted.

## Next steps

- [Upload and download objects](upload-and-download-objects.md)
- [Make objects public](make-objects-public.md)
- [Turn on versioning](turn-on-versioning.md)
