# Use a custom domain for a website

Answer a bucket's static website on a domain of your own, such as www.example.com, with a certificate issued on the first visit.

Replace _example-site_ with your bucket's name and _www.example.com_ with your domain.

## Prerequisites

- The bucket serves a website (see [Host a static website](host-a-static-website.md)).
- Permission for `s3:PutBucketWebsite` on the bucket (and `s3:DeleteBucketWebsite` to remove a
  domain).
- In the console, also `s3:GetBucket` on the bucket to open it (without it the bucket's page says
  "Access denied").
- The domain is not already the domain of another website.

## Add the domain

**Console**
1. Open the bucket, then choose **Website**. **Custom domains** appears once the website is on.
2. Under **Custom domains**, choose **Add domain**.
3. In **Add custom domain**, for **Domain**, enter www.example.com in lower case.
4. Choose **Add domain**.

The **DNS** column says either **ALIAS record in your Deutsche Cloud DNS zone** or **Create at your
DNS host:** followed by `CNAME example-site.s3-website.<domain>`, the website's host.

**CLI**
```sh
dcloud s3 bucket-access add-domain example-site --domain '"www.example.com"'
```

**API**
```http
POST /s3/api/buckets/example-site/website/domains
{ "domain": "www.example.com" }
```

**Terraform**
```hcl
resource "dcloud_bucket_domain" "www" {
  bucket = dcloud_bucket.site.id
  domain = "www.example.com"
}
```

`cname_target` is the host to point the CNAME at.

## Point the name at the website

- If the domain is in a zone of your organization in Deutsche Cloud DNS, and nothing but an ALIAS to
  this bucket is at that name yet, the ALIAS record is written for you (`aliasRecordCreated:
true`).
- Otherwise create the record the answer names at your DNS host:
  `www.example.com CNAME example-site.s3-website.<domain>`.

A certificate is issued on the first HTTPS visit once the name resolves to Deutsche Cloud, and only
while the bucket's website is on. A domain belongs to one website at a time. Turning the website
off keeps its domains.

## Remove the domain

Choose **Remove** in the domain's menu (it is removed at once), or run
`dcloud s3 bucket-access remove-domain example-site www.example.com`.

## If it is refused

- 400 `domain: Not a valid domain name`.
- 400 `… is one of the platform's own names; the website already answers on example-site.s3-website.<domain>`.
- 409 `www.example.com is already the domain of a website`.

## Related

- [Host a static website](host-a-static-website.md)
- `s3.bucket-access.add-domain` · `dcloud s3 bucket-access add-domain` · `dcloud_bucket_domain`
