> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shuttle.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Domain names

> Add custom domains to your project

By adding a custom domain to your project, web traffic can be served on your own fancy domain name in addition to the default `<project-name>-<nonce>.shuttle.app`.

You can add a root-level domain (`example.com`) or a subdomain (`thing.example.com`).

Adding a custom domain to your project follows these steps:

* Purchase a domain name from a DNS provider,
* set up a DNS record to make it point to your Shuttle server, and
* generate an SSL certificate that enables HTTPS traffic to your project.

## 1. Set up DNS record

The process for setting up the required DNS rule looks different depending on which type of domain and registrar you have.

> [accordion] Cloudflare
>
> If you have your domain name on Cloudflare, the process is quite simple. Go to `Websites -> <your domain> -> DNS -> Records -> Add Record`, then follow the relevant section below.
>
> ### Root domain
>
> Add a `CNAME` record from `@` to your `*.shuttle.app` subdomain. The Cloudflare proxy can be enabled or disabled,
> depending on your needs.
>
> ![cloudflare root cname](https://mintcdn.com/shuttle/ISqfIZfTiW4muc41/images/cloudflare_root_cname.png?fit=max\&auto=format\&n=ISqfIZfTiW4muc41\&q=85\&s=666d9ba5764c0c5c714c85dea45b0eae)
>
> Adding a `CNAME` on the root level here is possible due to Cloudflare's [CNAME flattening](https://developers.cloudflare.com/dns/cname-flattening/).
>
> You can also add a `CNAME` for the `www` subdomain if you also want traffic to `www.example.com` to arrive to your service.
>
> ### Subdomain
>
> Add a `CNAME` record from your subdomain to your `*.shuttle.app` subdomain. Disable the Proxy.
>
> ![cloudflare subdomain cname](https://mintcdn.com/shuttle/ISqfIZfTiW4muc41/images/cloudflare_sub_cname.png?fit=max\&auto=format\&n=ISqfIZfTiW4muc41\&q=85\&s=57604afdefeb5a7a08d2135aeea5ae1d)
>
> In the example above, the subdomain `my-subdomain` (as in `my-subdomain.my-domain.com`) is being directed to `my-project-0000.shuttle.app`.

> [accordion] Other DNS providers
>
> The process for other providers can vary, but here are the general steps. If you want to add docs for a specific provider, feel free to contribute to this page.
>
> ### Root domain
>
> If you are adding a root-level domain, add one or more `A` records that point to the same IP
> addresses that are returned when you do a DNS lookup for your default shuttle domain, e.g.
> `example.shuttle.app`.
>
> On Mac or Linux, we can use the `dig` tool in the terminal:
> `dig +short A example.shuttle.app`
>
> On Windows you can use `nslookup` in the terminal, or browser based equivalents like
> [this](https://toolbox.googleapps.com/apps/dig/#A/).
>
> ### Subdomain
>
> If you are adding a subdomain, add a `CNAME` record from your subdomain to your `*.shuttle.app` subdomain.

## 2. Set up SSL certificate

### a. via Console

Once the DNS records have propagated, submit the domain name in your project's domain settings on the Console.

### b. via CLI

Once the DNS records have propagated, add an SSL certificate and start receiving HTTPS traffic by running:

```bash theme={null}
shuttle certificate add <domain>
```

After that, you can manage certificates with:

```bash theme={null}
shuttle certificate list
shuttle certificate delete <domain>
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.