Markdown
English Deutsch

Publishing

Set DNS with DigitalOcean

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

On this page

If your domain’s DNS lives in a DigitalOcean 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.

API token at DigitalOcean

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

  1. Sign in to the DigitalOcean control panel 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.
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