# Map a custom domain

> Point a hostname you own at an Ownkube deployment with a single CNAME record.

Every public web deployment on Ownkube gets an auto-allocated hostname under `*.ownkube.app` with automatic TLS. If you want to serve the same deployment from a hostname you own (`api.acme.com`, `app.acme.com`), add a CNAME record at your DNS provider that points at the auto-allocated hostname.

**TLS on the custom hostname is not yet managed by Ownkube.** The CNAME mapping works today, but Ownkube does not currently issue certificates for hostnames it does not own. Terminate TLS in front of Ownkube (Cloudflare proxy, your own load balancer, or a similar edge) until automatic certificate issuance ships. Email [support@ownkube.io](mailto:support@ownkube.io?subject=Custom%20domain%20TLS) if you need help.

## Before you start

- You need an active web deployment with **Make this deployment public** turned on. See [Deployments](/docs/features/deployments).
- You need access to the DNS zone for the hostname you want to use (Cloudflare, Route53, Namecheap, etc.).

## Steps

1. **Copy the auto-allocated hostname**

   Open your deployment from your [dashboard](https://app.ownkube.io/dashboard). On the **Overview** tab, find the public URL. It looks like `https://your-app-production-a1b2c3.ownkube.app`. Copy the hostname (everything after `https://`, no trailing slash).

2. **Create a CNAME record**

   At your DNS provider, add a record for the hostname you want to expose:

   | Field | Value |
   |---|---|
   | Type | `CNAME` |
   | Name / Host | the subdomain you want (e.g. `api`) |
   | Target / Value | the auto-allocated hostname from step 1 |
   | TTL | `300` (5 minutes) is a reasonable default |
   | Proxy / Cloud icon | **on** if you're using Cloudflare and want it to terminate TLS, otherwise **off** |

   Apex domains (`acme.com` with no subdomain) cannot use a CNAME at most providers. Use a subdomain like `www.acme.com` or `app.acme.com`, or use your provider's `ALIAS` / `ANAME` record type if it supports one.

3. **Wait for DNS to propagate**

   Most providers update within a minute or two. You can check with `dig` or `nslookup`:

   ```bash
   dig +short api.acme.com CNAME
   ```

   The output should show the auto-allocated `*.ownkube.app` hostname.

4. **Terminate TLS at your edge**

   Because Ownkube does not yet issue certificates for custom hostnames, point a TLS-terminating proxy at the auto-allocated hostname:

   - **Cloudflare**: turn the orange-cloud proxy on for the CNAME record. Cloudflare issues a certificate for `api.acme.com` and forwards traffic to Ownkube over HTTPS.
   - **Your own load balancer**: attach a certificate for `api.acme.com` and configure the origin as the auto-allocated `*.ownkube.app` hostname over HTTPS.

   Traffic between your edge and Ownkube is always served over HTTPS using the cert Ownkube manages on the `*.ownkube.app` hostname.

5. **Verify**

   Open `https://api.acme.com` in a browser. You should see your app, served over TLS via your edge.

## What Ownkube sees

Requests still arrive at the auto-allocated `*.ownkube.app` hostname (your edge proxies to it), so the `Host` header your container receives is the `*.ownkube.app` hostname. If your app reads `Host` to build absolute URLs, configure your edge to forward the original host header (`X-Forwarded-Host`) and have your app prefer that.

## Limits and constraints

- **One custom hostname per deployment** is the supported pattern today. Add multiple CNAMEs at your DNS provider if you need more, all pointing at the same auto-allocated hostname.
- **No apex domain support** without an `ALIAS` or `ANAME` record from your DNS provider. Subdomains work everywhere.
- **No managed TLS for custom hostnames yet.** Terminate at your edge.
- **No HTTP to HTTPS redirect** on the custom hostname unless your edge does it. Ownkube redirects on the auto-allocated hostname.

## Roadmap

- **Managed TLS on customer hostnames.** Ownkube will issue and rotate certificates for hostnames you've mapped, so you won't need a TLS-terminating edge.
- **Apex domain support** via DNS challenge once managed TLS ships.

- [Deployments](/docs/features/deployments)
- [Deploy your first app](/docs/guides/deploy-first-app)

---

**Don't see a feature you need?** Email [support@ownkube.io](mailto:support@ownkube.io?subject=Feature%20request). Ownkube is shaped by the teams using it and we ship what our users ask for.