add_domain
Serve a deployed app at your own domain via the node's embedded proxy at the root path, using internal CA by default or requesting a public ACME certificate; point DNS to this machine first.
Instructions
Serve a deployed app at a domain YOU own, from this node's own proxy (P26).
Unlike ``share_service`` (Nerdit's domain, over the cloud tunnel), this
is the node's embedded Caddy answering ``https://<domain>/`` directly —
in either proxy mode, at the ROOT, so a frontend needs no ``/<app>/``
base path. The one thing the daemon cannot do for you: point the
domain's DNS (A/AAAA/CNAME) at this machine. By default the domain is
served with the node's internal CA, so a client must run
``nerdit trust`` once. ``acme=True`` requests a public ACME
certificate; it needs an ADMIN token (403 ``domain.acme_forbidden``,
``reason: acme_admin_only`` — the node has one ACME account whose rate
limits every domain on it shares) and 409 ``domain.acme_disabled``
unless the daemon has ``[proxy.acme].enabled``.
Refusals:
422 ``domain.invalid`` — the name broke exactly one grammar rule and the
message names it (``empty``, ``whitespace``, ``not_bare``,
``has_port``, ``wildcard``, ``ip_literal``, ``idn``, ``single_label``,
``grammar``, ``reserved``); 409 ``domain.taken`` (one domain, one
service — never silently re-pointed); 422 ``domain.kind_unsupported``
(models and databases are not routed).
Returns ``{domain, url, state, cert_state, created}``; ``state`` is
``ready`` | ``withheld`` (``withheld`` = the proxy is off, the app is
not routed yet, or its ``[deploy].edge_auth`` secret does not resolve —
the row is stored either way and answers once it is). ``cert_state`` is
the orthogonal certificate fact: ``internal`` (this node's CA) |
``disabled`` (``acme`` asked for, ``[proxy.acme]`` off) | ``pending``
(issuing, or failing — check ``doctor``) | ``issued`` | ``expired``.
The URL then appears in ``get_service`` / ``list_routes`` under
``public_urls`` (kind ``domain``).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| acme | No | Tri-state certificate policy. ``true`` = request a public ACME certificate; ``false`` = serve with this node's internal CA; omit (the default ``null``) = keep the row's stored value, ``false`` on a new domain — so a re-run never downgrades an issued certificate. | |
| name | Yes | Name (or row id) of an existing deployed app — only kind 'service' can be exposed: ``share_service``/``add_domain`` refuse a model or database with 422 ``*.kind_unsupported``, while the remove tools just find nothing to undo. | |
| domain | Yes | Bare lowercase DNS name of at least two labels: no scheme, path, port, wildcard, IP literal or IDN/punycode. Case and one trailing dot are folded server-side, so ``App.Example.COM.`` and ``app.example.com`` are one resource. A name at or under this node's own hostname, ``base_domain`` or ``extra_hostnames`` is reserved. | |
| idempotency_key | No | Caller-chosen key: a retry with the same key replays the first result instead of acting twice. Omit and a fresh key is minted per call, so each call acts. |