# Set DNS with DigitalOcean

Connect a DigitalOcean API token once. MainPath writes A and CNAME records into your domains.

> Source: https://www.mainpath.ai/en/docs/dns-digitalocean/

If your domain's DNS lives in a [DigitalOcean](https://www.digitalocean.com/) account, you no longer have to copy records by hand. You store an API token under **Connections**; once a project has domains, MainPath writes the records into the matching domain.

Manual DNS is still possible. See [Configure a DNS record]({{< relref "domain-how-to" >}}).

## API token at DigitalOcean

MainPath talks to the **DigitalOcean Domains API** (`api.digitalocean.com/v2/domains`).

1. Sign in to the [DigitalOcean control panel](https://cloud.digitalocean.com/) and open **API**.
2. Create a **Personal Access Token** with read and write for domains.
3. Copy the token. It is shown only once.

The domain must use DigitalOcean nameservers (`ns1.digitalocean.com`, `ns2.digitalocean.com`, `ns3.digitalocean.com`).

## Connection in MainPath

1. Open **Connections** and **Add connection**.
2. Under **DNS**, choose the **DigitalOcean** tile.
3. Paste the API token and save. MainPath checks whether the token is valid and which domains it can see.

Several DigitalOcean connections in one organization are allowed. If a hostname matches more than one zone, MainPath uses the most specific one.

## What is written

MainPath uses the same hosts you see under **Domains**.

- Records are only written when a real server address already exists.
- Existing records of the same name and type are updated; the whole zone is never replaced.
- Changes usually show up quickly.

```mermaid
flowchart LR
  org["DigitalOcean connection"]
  domains["Domains in MainPath"]
  zone["DigitalOcean domain"]
  server["Your server"]
  org --> zone
  domains -->|"A / CNAME"| zone
  zone --> server
```

After you save a project, MainPath tries to align missing or mismatched records. You can see the check status in the domain overview.

## SSL via DNS-01 (optional)

If Let's Encrypt cannot reach the server (no public HTTP/443, firewall, internal IP), open this connection's details and tick the affected domains. MainPath then writes the `_acme-challenge` TXT record into this zone. Unticked domains keep the existing TLS-ALPN challenge on the server.

## Troubleshooting

- **Invalid token**: Create a Personal Access Token with domain read and write. A read-only token is not enough.
- **No record at DigitalOcean**: The domain is not in this account, or it uses other nameservers.
- **Zone visible, domain unreachable**: The domain exists at DigitalOcean, but the nameservers point elsewhere. Point the nameservers at the registrar to DigitalOcean (`ns1.digitalocean.com`, `ns2.digitalocean.com`, `ns3.digitalocean.com`).
- **Status in MainPath still red**: DNS often takes a few minutes, or the server does not have a known address yet.

## See also

- [Domain setup]({{< relref "domain" >}})
- [Configure a DNS record]({{< relref "domain-how-to" >}})
- [Connections]({{< relref "connections" >}})