---
title: "Custom domains"
description: "Serve an app at a domain of its own, and the same code as several apps."
canonical_url: "https://docs.lightdrop.cloud/guides/custom-domains"
---
# Custom domains

> Serve an app at a domain of its own, and the same code as several apps.

Every app lives at `<app>.lightdrop.cloud`. It can also have domains of its own, like `example.com`
and `www.example.com`. Once a domain is verified, it serves the app with a certificate from
Let's Encrypt, and `<app>.lightdrop.cloud` forwards to it (308, path and query kept).

```bash
wervt domains my-app                          # list, with what to set in DNS
wervt domains my-app --add example.com
wervt domains my-app --verify example.com     # check DNS now instead of in a few minutes
wervt domains my-app --primary www.example.com
wervt domains my-app --remove example.com
```

The dashboard has the same under **Domains**. Only the app's owner (and admins) can change its
domains: they move the app for everyone who uses it.

## DNS

Point the domain at `domains.lightdrop.cloud`:

<table>
<thead>
  <tr>
    <th>
      Domain
    </th>
    
    <th>
      Record
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      A subdomain, <code>
        www.example.com
      </code>
    </td>
    
    <td>
      <code>
        CNAME domains.lightdrop.cloud
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      A bare domain, <code>
        example.com
      </code>
    </td>
    
    <td>
      <code>
        A
      </code>
      
       with the addresses of <code>
        domains.lightdrop.cloud
      </code>
      
       (<code>
        dig +short domains.lightdrop.cloud
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

wervt checks pending domains every few minutes and activates one as soon as it resolves to the
server. A domain belongs to one app at a time, and only whoever controls its DNS can point it here.

If the domain sits behind a proxy of your own, Cloudflare for instance, its addresses are the
proxy's. Add a TXT record instead, `_wervt.example.com` with the value `wervt-app=my-app`, and let
the proxy pass HTTP through on port 80, which Let's Encrypt uses to check the domain.

## The primary domain

An app's primary domain is its address: `WERVT_APP_URL`, the URL `wervt deploy` and the dashboard
show, the audience of its [App MCP](https://docs.lightdrop.cloud/guides/mcp) tokens and of agent tokens. Without a pick, it's the
first domain verified. Tokens issued for its other addresses stay valid.

## Signing in

Private apps work on custom domains. The `wervt_session` cookie belongs to `lightdrop.cloud`, so after
signing in the login sends the browser to `https://example.com/_wervt/session` once, with a token
valid for a minute, and the runtime sets the session as a cookie of the custom domain. Signing out
through `/_wervt/logout` clears both.

Public apps on a custom domain see a signed-in user once they went through `/_wervt/login` there.

## One codebase, several apps

The same code can run as several apps, each with its own database, files, access rules, env and
domains:

```bash
wervt deploy --name pueschi      # app "pueschi"
wervt deploy --name domos        # app "domos", same code
wervt domains pueschi --add pueschi.de
wervt domains domos --add domos.live
```

`--name` names the build too (`WERVT_APP`), so logs, the MCP server and link previews carry the
app's name rather than the one in `package.json`. Configure what differs per app with
`wervt env`. In GitHub Actions, give each app its own deploy token and run one deploy per app.


## Sitemap

See the full [sitemap](https://docs.lightdrop.cloud/sitemap.md) for all pages.
