feat(dstack-ingress): make the ACME contact address optional

Author: Kevin Wang

custom-domain/dstack-ingress/README.md

@@ -159,7 +159,7 @@ environment:
 | `DOMAIN` | Your domain (single-domain mode). Supports wildcards (`*.example.com`) |
 | `TARGET_ENDPOINT` | Backend address, e.g. `app:80` or `http://app:80` |
 | `GATEWAY_DOMAIN` | dstack gateway domain (e.g. `_.dstack-prod5.phala.network`) |
-| `CERTBOT_EMAIL` | Email for Let's Encrypt registration. In tls-alpn-01 mode the preferred name is `ACME_EMAIL` |
+| `CERTBOT_EMAIL` | Email for Let's Encrypt registration. Not required in tls-alpn-01 mode, where the preferred name is `ACME_EMAIL` |
 | `DNS_PROVIDER` | DNS provider (`cloudflare`, `linode`, `namecheap`) |
 
 ### Optional
@@ -172,7 +172,7 @@ environment:
 | `SET_CAA` | `false` | Enable CAA DNS record (dns-01 only; tls-alpn-01 cannot write DNS) |
 | `TXT_PREFIX` | `_dstack-app-address` | DNS TXT record prefix |
 | `CERTBOT_STAGING` | `false` | Use Let's Encrypt staging server. `ACME_STAGING` is the preferred name in tls-alpn-01 mode |
-| `ACME_EMAIL` | | ACME account email in tls-alpn-01 mode. Falls back to `CERTBOT_EMAIL`; there is no certbot on that path |
+| `ACME_EMAIL` | | Optional ACME contact address in tls-alpn-01 mode. Falls back to `CERTBOT_EMAIL`; there is no certbot on that path |
 | `CHALLENGE_TYPE` | `dns-01` | `dns-01` (certbot + DNS credentials) or `tls-alpn-01` (lego, no DNS credentials) |
 | `DNS_SETUP_MODE` | `wait` | tls-alpn-01 only: `wait`, `print` or `webhook` — see below |
 | `DNS_SETUP_TIMEOUT` | `1800` | tls-alpn-01 only: seconds to wait for the records to appear |
@@ -257,7 +257,7 @@ services:
       # Printed as the CNAME target, and used to verify that the hostname
       # really resolves to the gateway before issuance starts.
       - GATEWAY_DOMAIN=_.dstack-prod5.phala.network
-      - ACME_EMAIL=you@example.com
+      # - ACME_EMAIL=you@example.com   # optional, and published (see below)
       # - DNS_SETUP_MODE=wait          # default; blocks until the records exist
     ports:
       - "443:443"
@@ -307,6 +307,17 @@ Two consequences:
   means updating DNS. `DNS_SETUP_MODE=webhook` exists so this can be automated;
   doing it by hand means downtime on every redeploy.
 
+### The ACME contact address is optional, and public
+
+`ACME_EMAIL` may be left unset. RFC 8555 makes the ACME `contact` field
+optional, and Let's Encrypt stopped sending expiry notification mail in 2025, so
+setting one buys little.
+
+It also does not stay private. The ACME account document is published as
+attestation evidence at `/evidences/acme-account.json`, so an address set here
+is readable by anyone who fetches the evidence endpoint. Leave it unset unless
+you specifically want a contact on the account.
+
 ### Limitations
 
 - **No wildcards.** RFC 8737 forbids tls-alpn-01 for wildcard identifiers, and

custom-domain/dstack-ingress/scripts/legoman.py

@@ -25,6 +25,7 @@
 """
 
 import argparse
+import glob
 import json
 import os
 import subprocess
@@ -60,13 +61,20 @@ def server_dir() -> str:
     return f"{host}_{parsed.port}" if parsed.port else host
 
 
-def account_file(email: str) -> Optional[str]:
-    path = os.path.join(LEGO_PATH, "accounts", server_dir(), email, "account.json")
-    return path if os.path.isfile(path) else None
+def account_file() -> Optional[str]:
+    """Find the account document by globbing rather than by building the path.
 
+    lego names the directory after the account email, and after a placeholder of
+    its own choosing when there is no email. Globbing means we neither have to
+    know that placeholder nor track it across lego versions.
+    """
+    pattern = os.path.join(LEGO_PATH, "accounts", server_dir(), "*", "account.json")
+    matches = sorted(glob.glob(pattern))
+    return matches[0] if matches else None
 
-def account_uri(email: str) -> Optional[str]:
-    path = account_file(email)
+
+def account_uri() -> Optional[str]:
+    path = account_file()
     if not path:
         return None
     try:
@@ -96,15 +104,14 @@ def _renewed_marker(domain: str) -> str:
 
 
 def _common_flags(email: str) -> List[str]:
-    return [
-        "--path",
-        LEGO_PATH,
-        "--server",
-        acme_server(),
-        "--email",
-        email,
-        "--accept-tos",
-    ]
+    flags = ["--path", LEGO_PATH, "--server", acme_server(), "--accept-tos"]
+    # The ACME contact address is optional (RFC 8555 §7.3), and Let's Encrypt
+    # stopped sending expiry notifications in 2025, so it buys little. It is
+    # also published: the account document is served as evidence, so an address
+    # set here becomes public. Omit it unless the operator wants it.
+    if email:
+        flags += ["--email", email]
+    return flags
 
 
 def _run(cmd: List[str], timeout: int = RUN_TIMEOUT) -> Tuple[int, str]:
@@ -126,7 +133,7 @@ def _run(cmd: List[str], timeout: int = RUN_TIMEOUT) -> Tuple[int, str]:
 
 def register(email: str) -> int:
     """Create the ACME account without issuing anything."""
-    if account_file(email):
+    if account_file():
         print("ACME account already exists")
         return EXIT_UNCHANGED
 
@@ -135,7 +142,7 @@ def register(email: str) -> int:
         [LEGO_BIN, "accounts", "register"] + _common_flags(email),
         timeout=REGISTER_TIMEOUT,
     )
-    if code == 0 and account_file(email):
+    if code == 0 and account_file():
         print("✓ ACME account registered")
         return EXIT_CHANGED
     print(f"✗ ACME account registration failed (exit code {code})", file=sys.stderr)
@@ -214,10 +221,7 @@ def main() -> int:
     email = args.email or os.environ.get("ACME_EMAIL") or os.environ.get("CERTBOT_EMAIL", "")
 
     if args.action == "account-uri":
-        if not email:
-            print("Error: --email or ACME_EMAIL is required", file=sys.stderr)
-            return EXIT_ERROR
-        uri = account_uri(email)
+        uri = account_uri()
         if not uri:
             return EXIT_ERROR
         print(uri)
@@ -231,9 +235,6 @@ def main() -> int:
         print(f"{crt} {key}")
         return EXIT_CHANGED
 
-    if not email:
-        print("Error: --email or ACME_EMAIL is required", file=sys.stderr)
-        return EXIT_ERROR
     if not os.path.isfile(LEGO_BIN):
         print(f"Error: lego binary not found at {LEGO_BIN}", file=sys.stderr)
         return EXIT_ERROR

custom-domain/dstack-ingress/scripts/tlsalpn.sh

@@ -15,15 +15,15 @@ source /scripts/evidence-lib.sh
 # ACME account settings. CERTBOT_EMAIL / CERTBOT_STAGING are the historical
 # names, kept working for anyone migrating a compose file from dns-01, but there
 # is no certbot on this path -- the ACME client here is lego.
+#
+# The contact address is optional. RFC 8555 makes it optional, Let's Encrypt
+# stopped sending expiry notifications in 2025, and it does not stay private:
+# the account document is published at /evidences/acme-account.json, so an
+# address set here is readable by anyone who fetches the evidence.
 ACME_EMAIL=${ACME_EMAIL:-${CERTBOT_EMAIL:-}}
 ACME_STAGING=${ACME_STAGING:-${CERTBOT_STAGING:-false}}
 export ACME_EMAIL ACME_STAGING
 
-if [ -z "$ACME_EMAIL" ]; then
-    echo "Error: ACME_EMAIL must be set (CERTBOT_EMAIL is accepted as an alias)" >&2
-    exit 1
-fi
-
 LEGO_BIN=${LEGO_BIN:-/usr/local/bin/lego}
 LEGO_PATH=${LEGO_PATH:-/etc/letsencrypt/lego}
 TLSALPN_ADDRESS=${TLSALPN_ADDRESS:-127.0.0.1}
@@ -194,13 +194,13 @@ process_domain() {
     # Register the ACME account first so the CAA record we print can already
     # pin accounturi. Without this the operator would have to add CAA in a
     # second pass, after the account exists.
-    if ! legoman.py register --email "$ACME_EMAIL"; then
+    if ! legoman.py register ${ACME_EMAIL:+--email "$ACME_EMAIL"}; then
         echo "Error: failed to register the ACME account" >&2
         exit 1
     fi
 
     local account_uri caa_value
-    account_uri=$(legoman.py account-uri --email "$ACME_EMAIL" 2>/dev/null || true)
+    account_uri=$(legoman.py account-uri 2>/dev/null || true)
     if [ -n "$account_uri" ]; then
         caa_value="letsencrypt.org;validationmethods=tls-alpn-01;accounturi=$account_uri"
     else
@@ -244,7 +244,7 @@ process_domain() {
         sleep "${DNS_SETTLE_SECONDS}"
     fi
 
-    legoman.py auto --domain "$domain" --email "$ACME_EMAIL"
+    legoman.py auto --domain "$domain" ${ACME_EMAIL:+--email "$ACME_EMAIL"}
 }
 
 # One pass over every domain: make sure the records exist, then issue or renew.