Custom domains

Serve tela to your team on a domain you control — wiki.acme.com instead of the shared host. For your members, your custom domain is tela: they sign in, open their spaces, edit, and share, all under your own address and branding.

[!NOTE] A custom domain is a front door, not a separate instance. Accounts, organizations, spaces, and access work exactly as before — only the address, the branding, and which sign-in methods show are different. Your data lives in the same tela.

What a custom domain changes (and what it doesn't)

[!IMPORTANT] Don't confuse this with auto-join email domains ([[Administration|Administration → Organizations]]). That feature maps an email domain (acme.com) to an org for membership. A custom domain is a web address (wiki.acme.com) your app is served on. Different things.

Before you start

• You're an org admin (or instance admin) for the organization.
• You control DNS for a subdomain you'll point at tela (e.g. wiki.acme.com — a root domain like acme.com won't work).
• The operator has enabled direct-TLS mode on the instance (see the callout at the end). On the managed host this is already handled.

How it works

sequenceDiagram
  participant A as Org admin
  participant T as tela
  participant D as Your DNS
  A->>T: Add wiki.acme.com (Settings → org → Custom domains)
  T-->>A: TXT challenge + CNAME target to set
  A->>D: Add the TXT and CNAME records
  A->>T: Click Verify
  T->>D: Resolve the TXT challenge
  T-->>A: Verified → Active. Certificate issues on first visit

Step 1 — Add the domain

Go to Settings → Organizations → (your org) → Custom domains, enter the subdomain (wiki.acme.com), and click Add. It appears as Pending with the two DNS records you need to set.

Step 2 — Set DNS

Add both records at your DNS provider. tela shows you the exact values (with copy buttons).

[!TIP] If your DNS provider can't CNAME the record (or you prefer it), an A record pointing the subdomain at the instance's IP works too. The TXT record is always required — it's how tela confirms you own the name.

Step 3 — Verify

Click Verify. tela looks up the TXT record; on a match the domain flips to Active and a TLS certificate is issued automatically the first time someone visits. DNS can take a few minutes to propagate — if verification fails, tela retries briefly, and you can click Retry verify any time.

[!NOTE] Instance admins can activate a domain without the TXT check (for a domain wired up out of band). Org admins always go through DNS verification.

Checking a domain's health

Each domain has a Check action that probes it live and reports two signals:

• DNS — does the hostname resolve, and does it point at a public address (this instance)?
• HTTPS — is it serving over HTTPS with a valid certificate yet?

Use it to tell "DNS hasn't propagated" apart from "the certificate hasn't issued" when a domain isn't loading.

[!TIP] Once a domain is Active, an instance admin sees an Open button on it — it signs them in on that domain in a new tab. Handy when the org enforces SSO and the admin's own identity isn't in the org's IdP.

Step 4 — Choose sign-in methods

In the same Custom domains tab, Login methods controls what your domain's sign-in screen offers:

• Password sign-in — turn off to require SSO/social only.
• Social sign-in — show or hide the Google/Microsoft/GitHub buttons.

When your organization has [[Single Sign-On (SSO)]] configured, your domain's login screen shows a one-click "Sign in with {your org}" button — no email prompt, because the domain already identifies the org.

[!WARNING] You can't turn both password and social off unless the org has SSO configured — that would lock everyone out. tela blocks it, and the password toggle is enforced on the server, not just hidden.

Step 5 — Brand it

In the Branding section of the Custom domains tab, set:

• Logo — an https:// URL to your logo image. It replaces the tela wordmark on the login screen and across the app on your domain.
• Accent color — a hex (#4f46e5) or oklch(…) / rgb(…) value. It themes buttons, links, and accents throughout the app on your domain.

Leave either blank to fall back to tela's default. The change applies to everyone visiting your custom domain (it doesn't affect the main host).

[!TIP] Your branding also rides along on link previews. When a page, share link, or public space on your domain is pasted into Slack, Teams, Discord, iMessage, and the like, the preview card shows your logo, accent color, and org name instead of tela's — so a shared link looks like yours everywhere it lands. (Decks keep showing their cover slide.)

[!TIP] Your branding also rides into the transactional emails tela sends on your domain — sign-up confirmation, password reset, and notification emails (mentions, replies, page updates). Each shows your logo, accent, and org name, with a small "Powered by tela" credit in the footer — so the mail in your members' inboxes looks like yours, not tela's. (Email clients can't render oklch() colors, so an oklch accent falls back to tela's indigo in email only — set a hex or rgb() accent if you want your exact color there too.)

What your members experience

• They visit your domain and see a sign-in screen with your name, logo, and colors.
• They sign in on your domain (sessions are per-domain — a session from the main host doesn't carry over, and vice-versa; this keeps each front door cleanly separate).
• Confirmation / password-reset emails and the links they share all point back to your domain.
• Everything else — their spaces, what they can access, the editor — is exactly as it is anywhere else in tela.

Removing a domain

Delete it from the Custom domains tab. Its login screen stops working immediately. You can re-add it later, but it'll need DNS verification again.

[!IMPORTANT] For operators / self-hosters: custom domains require the instance to run in direct-TLS mode — tela (via Caddy) terminates HTTPS itself and issues a certificate on demand for each verified domain. This does not work behind Cloudflare (or another proxy that terminates TLS), because the on-demand certificate step never runs. Set TELA_SITE_ADDRESS to your canonical host and publish ports 80 + 443. See [[Self-Hosting]].

Troubleshooting

See also: [[Administration]] · [[Single Sign-On (SSO)]] · [[Self-Hosting]]