> ## 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.

<AccordionGroup>
  <Accordion title="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.

    <img src="https://mintcdn.com/shuttle/ISqfIZfTiW4muc41/images/cloudflare_root_cname.png?fit=max&auto=format&n=ISqfIZfTiW4muc41&q=85&s=666d9ba5764c0c5c714c85dea45b0eae" alt="cloudflare root cname" width="1186" height="110" data-path="images/cloudflare_root_cname.png" />

    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.

    <img src="https://mintcdn.com/shuttle/ISqfIZfTiW4muc41/images/cloudflare_sub_cname.png?fit=max&auto=format&n=ISqfIZfTiW4muc41&q=85&s=57604afdefeb5a7a08d2135aeea5ae1d" alt="cloudflare subdomain cname" width="1189" height="110" data-path="images/cloudflare_sub_cname.png" />

    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>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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>
```