# Custom Domains

## Default URLs

Every service and app gets a URL under `*.compacthive.dev`:

```
https://<your-slug>-<service>.compacthive.dev
```

Examples: `https://acme-ci.compacthive.dev` (Woodpecker CI), `https://acme-grafana.compacthive.dev` (Grafana), `https://acme-my-api.compacthive.dev` (a custom app). These work immediately after deployment; TLS is handled for you.

## Adding a custom domain

Custom domains are available on **every tier**, with a per-tier limit on how many you can register:

| Tier | Custom domains |
|---|---|
| Basic | 3 |
| Team | 10 |
| Pro | 25 |
| Business | 50 |
| Enterprise | Effectively unlimited |

1. Go to portal → **Domains**.
2. Enter your hostname, pick the service or app it should point to, and click **Add Domain**.
3. At your DNS provider, add a **TXT record** named `_compacthive-challenge.<host>` with the exact value shown in the domain's verification card. For example, for `app.example.com`, the full record name is `_compacthive-challenge.app.example.com`. Some providers append your zone name automatically; check that it is not duplicated. Use the copy buttons for the name and value.
4. Add an **A record** for your hostname pointing at the IP address shown in the DNS instructions. **AAAA/IPv6 is not supported yet — use an A record only.** Use an A record, **not a CNAME** — a CNAME to `compacthive.dev` does not work for a domain you own (it is a Cloudflare-proxied name in CompactHive's account, so foreign hostnames are rejected at Cloudflare's edge).
5. Click **Verify now** after DNS propagates, or wait for an automatic check. CompactHive checks the TXT record to verify ownership, then checks that the A record points at its ingress.
6. Once verified and pointing at CompactHive, a **Let's Encrypt certificate is issued automatically**, typically within minutes. When the status is **Active**, HTTP redirects to HTTPS. Certificates renew automatically; keep your DNS pointing at CompactHive.

A hostname can only be claimed by one account. CompactHive-owned names cannot be used as your own custom domains. Unverified domains are removed after **7 days**; add the domain again if you need to restart verification. Until ownership is verified, the domain does not route traffic to your app.

## Domain status

| Status | Meaning | What to do |
|---|---|---|
| Pending verification | Ownership has not been confirmed; traffic is not routed yet. | Add the TXT record exactly as shown, wait for DNS propagation, then click **Verify now** or wait for an automatic check. Check the removal countdown. |
| Verified | Ownership is confirmed; CompactHive is waiting for your A record. | Point the A record at the IP shown in the portal and wait for the DNS check. |
| Issuing certificate | The hostname is ready and a certificate is being requested. | Wait a few minutes. If an error is shown, check DNS and your proxy settings. Automatic retries may take longer. |
| Active | The certificate is installed and HTTPS is ready. | Open your domain. Keep DNS pointing at CompactHive so automatic renewal can succeed. |
| Error | Certificate issuance requires attention. | Read the error, correct DNS or proxy settings, then click **Retry**. Contact support if it persists. |

If an existing domain shows a verification deadline banner, add the TXT record and verify ownership by that date or the domain stops working.

## Cloudflare and other proxies

For Cloudflare-proxied customer records, use **DNS-only (grey cloud)** during issuance, or configure the proxy to pass `/.well-known/acme-challenge` requests through to CompactHive. Let's Encrypt needs to reach that path over HTTP to issue and renew certificates. Keep the challenge path reachable for automatic renewal too.