From ff0dbcb4363c2fad29eef60fbbe258cedc21f66e Mon Sep 17 00:00:00 2001
From: SaladDay <1203511142@qq.com>
Date: Wed, 30 Sep 2026 08:36:14 +0000
Subject: [PATCH 1/2] Publish the managed gateway's ports 80 and 443 only for
 HTTPS

The gateway publishes ports.web always, and 80 and 443 once public_url is
set or while domain setup verifies a candidate address
(ingress_config.published). configuration.listeners follows, so a new
installation checks 80 and 443 only with --public-url and oac apply
checks them when public_url turns HTTPS on.

Domain setup (Web and oac domain) checks, before it reserves a job, that
the hostname resolves (hostname_unresolved, 409) and that no other
program holds 80 or 443 (https_ports_unavailable, 409). The installation's
own listeners include those of the written gateway, so a domain change
with HTTPS on, or a retry after an interrupted attempt, never fails on
the gateway's own ports. The attempt renders the candidate through the
common apply, which recreates the gateway with 80 and 443 before Caddy
verifies it; failure restores the gateway without them. The
verification failure message now names DNS, firewall or NAT, and the
certificate request as its causes.

The fake host's listening table includes the ports running containers
publish.
---
 deploy/install/README.md                |  4 +-
 deploy/install/configuration.py         | 22 +++++-----
 deploy/install/ingress.py               | 41 ++++++++++++++-----
 deploy/install/ingress_config.py        | 25 +++++++++---
 deploy/install/install_output.py        |  2 +-
 deploy/install/installer_fakes.py       | 21 ++++++----
 deploy/install/oac_cli.py               | 54 ++++++++++++++++---------
 deploy/install/test_ingress.py          | 39 ++++++++++++++++--
 deploy/install/test_install.py          | 11 ++++-
 docs/configuration.md                   |  4 +-
 docs/getting-started/install-options.md | 10 ++---
 docs/getting-started/install.md         |  6 +--
 docs/getting-started/operations.md      |  7 ++--
 13 files changed, 175 insertions(+), 71 deletions(-)

diff --git a/deploy/install/README.md b/deploy/install/README.md
index 9e2f4d392..abf3c8f18 100644
--- a/deploy/install/README.md
+++ b/deploy/install/README.md
@@ -65,8 +65,8 @@ This directory holds the Core/Web installer, the `oac` command and the node inst
 
 A default combined Docker installation adds two Compose services from one pinned image: `gateway` runs Caddy, and `installation` runs the packaged `oac domain-server`. The latter runs with the installing account's UID and its Docker socket access and calls the same locked apply implementation. Its only request surface is the private `ingress/api/api.sock`, with Core-key authentication and one typed domain action. Core and Web get no Docker socket, host process authority or writable installation configuration. Web gets only the private API socket directory, never Caddy's admin socket.
 
-- The gateway owns ports 80 and 443 and the initial Web port. Caddy issues and renews certificates and keeps its private data in `ingress/data`. `generated/Caddyfile` is derived from `config.json`, and apply reloads it through the private Caddy socket even when container inputs already match.
-- A domain change keeps the old entry point while it verifies a trusted certificate and an installation-specific response over HTTPS. Only then does it set `public_url` and call the common apply path. Failure restores the previous configuration and reports incomplete recovery; failed retries restore through the common apply even after a partial change.
+- The gateway publishes the initial Web port, and ports 80 and 443 only for HTTPS (`ingress_config.published`). Caddy issues and renews certificates and keeps its private data in `ingress/data`. `generated/Caddyfile` is derived from `config.json`, and apply reloads it through the private Caddy socket even when container inputs already match.
+- A domain change first checks that the hostname resolves and that no other program holds port 80 or 443; ports the written gateway already publishes are its own. It keeps the old entry point while the common apply renders the candidate address: the gateway publishes 80 and 443 and serves the candidate, and the verification needs a trusted certificate and an installation-specific response over HTTPS. Only then does it set `public_url` and apply again. Failure restores the previous configuration, including the gateway without 80 and 443 when HTTPS was off, and reports incomplete recovery; failed retries restore through the common apply even after a partial change.
 - The operation record keeps the last successfully applied public address. Apply and start update it after gateway verification and service health checks; generated files alone never prove that a new address is active. A successful apply reconciles the domain operation status after verifying the running services.
 - The domain operation refuses unrelated pending `config.json` edits and shares `.oac.lock` with the CLI. Its status file is bookkeeping and the recovery receipt; `config.json` stays the source of desired settings. An interrupted operation keeps its desired files and a visible failure and retry state; it never creates another service project or deletes execution data.
 - A Web restart ends console sessions, so the UI gives the new HTTPS sign-in address instead of treating a dropped request as success.
diff --git a/deploy/install/configuration.py b/deploy/install/configuration.py
index a5582c5c9..fb73ada62 100644
--- a/deploy/install/configuration.py
+++ b/deploy/install/configuration.py
@@ -146,16 +146,18 @@ def service_address(config, service, connect=False):
 Listener = collections.namedtuple("Listener", "purpose host port setting")
 
 
-def listeners(config):
+def listeners(config, candidate=None):
     """Every host listener the services bind, from the addresses they are rendered with.
 
-    setting is the config.json key that owns the port.
+    setting is the config.json key that owns the port. candidate is the address domain
+    setup verifies, as in render.
     """
     mode, ports, result = config["mode"], config["ports"], []
     if ingress_config.enabled(config):
-        # The gateway publishes Web's port and the HTTPS ports; Web itself publishes none.
+        # The gateway publishes Web's port and, for HTTPS, 80 and 443; Web itself publishes none.
         result += [Listener("Web", config["host"], port, "ports.web") if port == ports["web"] else
-                   Listener("HTTPS", config["host"], port, "ingress") for port, _ in ingress_config.published(config)]
+                   Listener("HTTPS", config["host"], port, "public_url")
+                   for port, _ in ingress_config.published(config, candidate)]
     elif mode != "core-only":
         result.append(Listener("Web", service_host(config, "web"), ports["web"], "ports.web"))
     if mode != "web-only":
@@ -229,7 +231,7 @@ def settings_document(root, config, applied_at):
             "applied_at": applied_at, "settings": config_model.settings(config)}
 
 
-def compose_config(root, config, state):
+def compose_config(root, config, state, candidate=None):
     root = Path(root)
     mode, native = config["mode"], config.get("native_core", False)
     identity = f'{state["uid"]}:{state["gid"]}'
@@ -297,7 +299,7 @@ def compose_config(root, config, state):
             web["volumes"].append(bind(root / "ingress/api", "/installation"))
         services["web"] = web
     if ingress_config.enabled(config):
-        services.update(ingress_config.services(root, config, state, bind))
+        services.update(ingress_config.services(root, config, state, bind, candidate))
     return doc
 
 
@@ -327,7 +329,9 @@ def native_installer_inputs(root):
     return [sha256(catalog.read_bytes()), sorted(p.name for p in directory.glob("*.tar.gz") if p.is_file())]
 
 
-def render(root, config, state, applied_at):
+def render(root, config, state, applied_at, candidate=None):
+    """candidate is an HTTPS address domain setup verifies before public_url changes:
+    the gateway publishes 80 and 443 and serves it too."""
     root = Path(root)
     mode, native = config["mode"], config.get("native_core", False)
     secrets = secret_digests(root, mode)
@@ -354,7 +358,7 @@ def render(root, config, state, applied_at):
         }, sort_keys=True)
     if mode != "core-only":
         external["web"] = json.dumps({"core.key": secrets["core.key"]})
-    compose = compose_config(root, config, state)
+    compose = compose_config(root, config, state, candidate)
     services = {}
     for name, service in compose["services"].items():
         # Compose resolves env_file into the service configuration, so its content counts.
@@ -362,7 +366,7 @@ def render(root, config, state, applied_at):
         services[name] = sha256(text + external.get("core" if name == "migrate" else name, ""))
         service["labels"] = {LABEL: services[name]}
     if ingress_config.enabled(config):
-        files["Caddyfile"] = ingress_config.caddyfile(config, state)
+        files["Caddyfile"] = ingress_config.caddyfile(config, state, candidate)
     files["compose.json"] = json.dumps(compose, indent=2) + "\n"
     if native:
         unit = native_service.unit_name(state)
diff --git a/deploy/install/ingress.py b/deploy/install/ingress.py
index d5c6caa54..109a1ad77 100644
--- a/deploy/install/ingress.py
+++ b/deploy/install/ingress.py
@@ -6,6 +6,7 @@
 from http.server import BaseHTTPRequestHandler
 import json
 from pathlib import Path
+import socket
 import socketserver
 import ssl
 import threading
@@ -84,6 +85,14 @@ def prepare(root, name, confirmation):
     rendered, disk, old_settings = oac_cli.render_now(root, config, state)
     if oac_cli.edited_files(state, disk, rendered):
         raise DomainError("generated_files_edited", "Resolve hand-edited generated files with oac apply before configuring the domain", 409)
+    host = urlsplit(target).hostname
+    if not resolves(host):
+        raise DomainError("hostname_unresolved", f"{host} does not resolve. Add A/AAAA records for it that point at this server, then retry when DNS returns them.", 409)
+    # The gateway publishes 80 and 443 only for HTTPS; the ports it already publishes are its own.
+    busy = [str(listener.port) for listener in oac_cli.taken_listeners(candidate, oac_cli.own_listeners(config, old_settings, disk))]
+    if busy:
+        named = f"Port {busy[0]} is" if len(busy) == 1 else "Ports " + " and ".join(busy) + " are"
+        raise DomainError("https_ports_unavailable", f"{named} already in use on this server. Automatic HTTPS cannot run beside another program on ports 80 and 443: free both and retry. Find the program with: sudo ss -ltnp '( sport = :80 or sport = :443 )'", 409)
     old, base, answered = oac_cli.old_public_url(root, config, old_settings, disk, actual)
     args = argparse.Namespace(dry_run=False, yes=False, confirm_public_url_change=confirmation)
     try:
@@ -95,6 +104,14 @@ def prepare(root, name, confirmation):
     return config, state, candidate, args, job
 
 
+def resolves(host):
+    """Whether DNS answers with an A or AAAA record."""
+    try:
+        return bool(socket.getaddrinfo(host, 443, type=socket.SOCK_STREAM))
+    except (OSError, UnicodeError):
+        return False
+
+
 def verify(target, installation_id, timeout=180):
     """A trusted certificate and this gateway's identity must both answer at the public address."""
     host = urlsplit(target).hostname
@@ -111,14 +128,18 @@ def verify(target, installation_id, timeout=180):
         except (OSError, http.client.HTTPException):
             pass
         if time.monotonic() >= deadline:
-            raise DomainError("https_not_ready", "HTTPS verification failed. Point this hostname's A/AAAA records at the server, allow inbound ports 80 and 443, and check gateway logs. The previous address is kept; retry after correcting DNS or connectivity.")
+            raise DomainError("https_not_ready", f"HTTPS verification failed: {host} did not reach this installation with a trusted certificate. Check that its A/AAAA records point at this server, that no firewall or NAT blocks inbound ports 80 and 443, and the gateway logs for certificate errors. The previous address is kept; retry after the fix.")
         time.sleep(2)
 
 
 def execute(root, prepared):
     config, state, candidate, args, job = prepared
+    # Core and Web keep the applied address until the candidate is verified.
+    keep = argparse.Namespace(dry_run=False, yes=False, confirm_public_url_change=configuration.local_public_url(config))
     try:
-        gateway.reload(root, gateway.caddyfile(config, state, candidate=candidate["public_url"]))
+        # Through common apply, the gateway publishes 80 and 443 and serves the candidate.
+        oac_cli.write_private(Path(root) / "config.json", json.dumps(config, indent=2) + "\n")
+        oac_cli._apply(Path(root), keep, False, False, False, lambda _: None, candidate=candidate["public_url"])
         verify(candidate["public_url"], state["installation_id"])
         job["state"] = "applying"
         save(root, job)
@@ -131,12 +152,10 @@ def execute(root, prepared):
     except Exception as error:
         recovery_failed = False
         try:
-            # A retry may inherit partially applied services from an interrupted
-            # attempt. Restore through common apply even if this attempt only probed TLS.
+            # Restore through common apply: the gateway without the candidate, and without
+            # 80 and 443 unless HTTPS was already on, and any partially applied services.
             oac_cli.write_private(Path(root) / "config.json", json.dumps(config, indent=2) + "\n")
-            restore = argparse.Namespace(dry_run=False, yes=False,
-                                         confirm_public_url_change=configuration.local_public_url(config))
-            oac_cli._apply(Path(root), restore, False, False, False, lambda _: None)
+            oac_cli._apply(Path(root), keep, False, False, False, lambda _: None)
             gateway.reload(root, gateway.caddyfile(config, state))
         except Exception:
             recovery_failed = True
@@ -232,14 +251,14 @@ def setup(self):
 
 def serve(root):
     root = Path(root)
-    socket = Path("/control/api.sock")
-    socket.unlink(missing_ok=True)
+    path = Path("/control/api.sock")
+    path.unlink(missing_ok=True)
     import os
     previous = os.umask(0o077)
     try:
-        with Server(str(socket), Handler) as server:
+        with Server(str(path), Handler) as server:
             server.root = root
-            os.chmod(socket, 0o600)
+            os.chmod(path, 0o600)
             server.serve_forever()
     finally:
         os.umask(previous)
diff --git a/deploy/install/ingress_config.py b/deploy/install/ingress_config.py
index 766b66d24..f3d90715d 100644
--- a/deploy/install/ingress_config.py
+++ b/deploy/install/ingress_config.py
@@ -107,12 +107,27 @@ def reload(root, document):
         raise RuntimeError("HTTPS gateway is unavailable; inspect gateway logs and retry") from None
 
 
-def published(config):
-    """(host port, gateway port) of each port the gateway publishes on config["host"]."""
-    return [(config["ports"]["web"], 8080), (80, 80), (443, 443)]
+def published(config, candidate=None):
+    """(host port, gateway port) of each port the gateway publishes on config["host"].
 
+    Automatic HTTPS needs ports 80 and 443, so the gateway publishes them only once
+    public_url is set, or while domain setup verifies a candidate address.
+    """
+    https = [(80, 80), (443, 443)] if config["public_url"] or candidate else []
+    return [(config["ports"]["web"], 8080)] + https
 
-def services(root, config, state, bind):
+
+def written_listeners(compose):
+    """(address, port) of each host port the gateway publishes in a written compose.json."""
+    try:
+        ports = json.loads(compose)["services"]["gateway"]["ports"]
+        return {(ipaddress.ip_address(host.strip("[]")), int(port))
+                for host, port, _ in (item.rsplit(":", 2) for item in ports)}
+    except (TypeError, ValueError, KeyError, AttributeError):
+        return set()
+
+
+def services(root, config, state, bind, candidate=None):
     root = Path(root)
     identity = f'{state["uid"]}:{state["gid"]}'
     common = {"image": state["images"]["ingress"], "user": identity, "restart": "unless-stopped",
@@ -121,7 +136,7 @@ def services(root, config, state, bind):
     if ":" in host:
         host = "[" + host + "]"
     gateway = dict(common, command=["caddy", "run", "--config", "/generated/Caddyfile", "--adapter", "caddyfile"],
-                   ports=[f"{host}:{port}:{target}" for port, target in published(config)],
+                   ports=[f"{host}:{port}:{target}" for port, target in published(config, candidate)],
                    environment={"XDG_DATA_HOME": "/data", "XDG_CONFIG_HOME": "/data/config",
                                 "NO_PROXY": "core,web,localhost,127.0.0.1,::1",
                                 "no_proxy": "core,web,localhost,127.0.0.1,::1"},
diff --git a/deploy/install/install_output.py b/deploy/install/install_output.py
index cf9adcaef..9c96a1ff3 100644
--- a/deploy/install/install_output.py
+++ b/deploy/install/install_output.py
@@ -56,7 +56,7 @@ def summary(root, config, addresses, fresh, selection, deployment, reachable, in
         paragraph("Use this key for the Core management API. Keep it private.")
     heading("Next")
     if ingress_config.enabled(config) and not config["public_url"]:
-        paragraph("Open Web at the server IP and sign in. In System → Domain and HTTPS, enter your DNS hostname; the installation requests and renews its certificate. DNS must point to this server and ports 80 and 443 must be reachable.")
+        paragraph("Open Web at the server IP and sign in. In System → Domain and HTTPS, enter your DNS hostname; the installation requests and renews its certificate. HTTPS then uses ports 80 and 443: DNS must point to this server, no other program on it may use those ports, and they must be reachable from the internet. Web checks DNS and the ports before it starts.")
     if mode != "core-only":
         paragraph("Create a Project and its API key on the Projects and keys page.")
     else:
diff --git a/deploy/install/installer_fakes.py b/deploy/install/installer_fakes.py
index 065e81c34..fdff8f6fb 100644
--- a/deploy/install/installer_fakes.py
+++ b/deploy/install/installer_fakes.py
@@ -2,9 +2,9 @@
 
 Compose is modelled by its observable contract: `up` recreates a container exactly
 when its resolved configuration (including env_file content) changed, each container
-keeps the labels it was created with, and Core loads its Core key digests when it
-starts. systemd runs the unit it last loaded; its process keeps the environment it
-started with.
+keeps the labels it was created with and holds the host ports it publishes while it
+runs, and Core loads its Core key digests when it starts. systemd runs the unit it
+last loaded; its process keeps the environment it started with.
 """
 import errno
 import hashlib
@@ -49,13 +49,13 @@ def __init__(self, test):
         self.deployment = {"provider": "", "generation": 0, "reset": None, "resources": {"allocations": 0, "pending": 0}}  # what sandbox_setup reads and posts
         self.deployment_posts = []
         self.deployment_refusal = None  # Core's message when it refuses the POST
-        self.busy = set()  # (address, port) of every listening socket, the installation's own included
+        self.busy = set()  # (address, port) of listening sockets besides the ports running containers publish
         self.unassigned = set()  # addresses this host does not have
         for target, name, value in ((subprocess, "run", mock.Mock(side_effect=self.run)),
                                     (oac_cli, "http", self.http),
                                     (oac_cli, "bind_error", self.bind_error),
                                     (oac_cli, "tcp_listeners", lambda: [(ipaddress.ip_address(host), port)
-                                                                        for host, port in self.busy]),
+                                                                        for host, port in self.listening()]),
                                     (oac_cli, "time", SimpleNamespace(sleep=lambda seconds: None)),
                                     (native_service, "_process_environment", self.process_environment),
                                     (sandbox_setup, "send", self.sandbox_send)):
@@ -68,11 +68,16 @@ def bind_error(self, host, port):
             return errno.EADDRNOTAVAIL
         address = ipaddress.ip_address(host)
         return errno.EADDRINUSE if any(held == port and oac_cli.overlaps(address, ipaddress.ip_address(other))
-                                       for other, held in self.busy) else 0
+                                       for other, held in self.listening()) else 0
 
     def running(self):
         return {name for name, item in self.containers.items() if item["running"]}
 
+    def listening(self):
+        """(address, port) of every listening socket: busy, and the ports running containers publish."""
+        return self.busy | {tuple(pair) for item in self.containers.values() if item["running"]
+                            for pair in item.get("ports", ())}
+
     def run_container(self, name, port=None, digests=None):
         """A container of an installation made outside the test, such as an earlier release."""
         self.containers[name] = {"hash": "external", "inputs": None, "running": True}
@@ -144,7 +149,9 @@ def compose(self, path, args):
                 current = self.containers.get(name)
                 if current is None or current["hash"] != digest:
                     self.containers[name] = {"hash": digest, "inputs": services[name].get("labels", {}).get(LABEL),
-                                             "running": False}
+                                             "running": False,
+                                             "ports": [[host.strip("[]"), int(port)] for host, port, _ in
+                                                       (item.rsplit(":", 2) for item in services[name].get("ports", []))]}
                     self.recreated.append(name)
                     if name == "core":
                         self.load_core(path.parent.parent, services[name])
diff --git a/deploy/install/oac_cli.py b/deploy/install/oac_cli.py
index 64c76ccf9..d7c52f107 100644
--- a/deploy/install/oac_cli.py
+++ b/deploy/install/oac_cli.py
@@ -245,8 +245,9 @@ def port_free(host, port, own=()):
 
 def port_in_use(listener, name, outcome=""):
     """The message for a port that another program holds; name is its flag or config.json key."""
-    return (f"Port {listener.port} ({name}) is already in use on {listener.host}.{outcome} Free it or choose another "
-            f"port; find the process with: sudo ss -ltnp 'sport = :{listener.port}'")
+    remedy = "Free it" if listener.purpose == "HTTPS" else "Free it or choose another port"
+    return (f"Port {listener.port} ({name}) is already in use on {listener.host}.{outcome} {remedy}; "
+            f"find the process with: sudo ss -ltnp 'sport = :{listener.port}'")
 
 
 def stale(actual, desired, will_run):
@@ -467,16 +468,16 @@ def disk_view(disk):
     return values, document.get("applied_at")
 
 
-def render_now(root, config, state):
+def render_now(root, config, state, candidate=None):
     """The render of config.json, keeping the written stamp unless something changed."""
     names = set((state.get("generated") or {}))
     disk = read_generated(root, names | {"settings.json", "runtime-history.json"})
     previous, stamp = disk_view(disk)
-    rendered = configuration.render(root, config, state, stamp or now())
+    rendered = configuration.render(root, config, state, stamp or now(), candidate)
     disk = read_generated(root, names | set(rendered.files) | {"runtime-history.json"})
     if any(comparable(name, disk.get(name)) != comparable(name, text) for name, text in rendered.files.items()) \
             or any(disk.get(name) is not None for name in names - set(rendered.files)):
-        rendered = configuration.render(root, config, state, now())
+        rendered = configuration.render(root, config, state, now(), candidate)
     return rendered, disk, previous
 
 
@@ -580,7 +581,22 @@ def check_paired_core(root, config, state, previous, args, interactive, out):
     return installation
 
 
-def check_new_listeners(config, previous):
+def own_listeners(config, previous, disk):
+    """(address, port) of this installation's listeners: those of the settings last written, and
+    those of the written gateway, which domain setup widens before public_url changes."""
+    applied = applied_view(config, previous)
+    return ({(ipaddress.ip_address(listener.host), listener.port) for listener in configuration.listeners(applied)}
+            | ingress_config.written_listeners(disk.get("compose.json")))
+
+
+def taken_listeners(config, own, candidate=None):
+    """The listeners of config, and of a domain candidate, that another program holds."""
+    return [listener for listener in configuration.listeners(config, candidate)
+            if (ipaddress.ip_address(listener.host), listener.port) not in own
+            and not port_free(listener.host, listener.port, own)]
+
+
+def check_new_listeners(config, previous, disk, candidate=None):
     """Each listener this change adds must be free; this installation's own listeners do not count."""
     if previous is None:
         return
@@ -588,23 +604,22 @@ def check_new_listeners(config, previous):
     if config["host"] != applied["host"] and not address_available(config["host"]):
         raise OacError(f"{config['host']} (host) is not an address of this machine; use one of its addresses. "
                        "Nothing was applied.")
-    own = {(ipaddress.ip_address(listener.host), listener.port) for listener in configuration.listeners(applied)}
-    for listener in configuration.listeners(config):
-        if (ipaddress.ip_address(listener.host), listener.port) not in own and \
-                not port_free(listener.host, listener.port, own):
-            raise OacError(port_in_use(listener, listener.setting, " Nothing was applied."))
+    taken = taken_listeners(config, own_listeners(config, previous, disk), candidate)
+    if taken:
+        raise OacError(port_in_use(taken[0], taken[0].setting, " Nothing was applied."))
 
 
-def finish_apply(root, config, state, gateway_document, will_run):
+def finish_apply(root, config, state, gateway_document, will_run, candidate=None):
+    """With a candidate, domain setup verifies it and records its own status."""
     managed = ingress_config.enabled(config) and "gateway" in will_run
     if managed:
         import ingress
         # Container input labels cannot prove which configuration Caddy loaded.
         ingress_config.reload(root, gateway_document)
-        if config["public_url"]:
+        if config["public_url"] and not candidate:
             ingress.verify(config["public_url"], state["installation_id"])
     health(root, config, will_run)
-    if managed:
+    if managed and not candidate:
         ingress.save(root, {"state": "ready" if config["public_url"] else "unconfigured",
                             "public_url": config["public_url"], "target_url": config["public_url"], "message": None})
 
@@ -618,20 +633,21 @@ def apply(root, dry_run=False, yes=False, discard_edits=False, confirm_public_ur
         return _apply(root, args, discard_edits, start, interactive, out, retry=retry)
 
 
-def _apply(root, args, discard_edits, start, interactive, out, rollback=True, retry=None):
+def _apply(root, args, discard_edits, start, interactive, out, rollback=True, retry=None, candidate=None):
+    """candidate: see configuration.render."""
     retry = retry or f"run {root / 'oac'} apply again"
     check_directories(root)
     config = load_config(root)
     state = load_state(root)
     check_fixed(config, state)
     check_secrets(root, config, state)
-    rendered, disk, previous = render_now(root, config, state)
+    rendered, disk, previous = render_now(root, config, state, candidate)
     edited = edited_files(state, disk, rendered)
     if edited and not discard_edits:
         raise OacError("\n".join(f"generated/{name} was edited by hand." for name in edited)
                           + "\nPut the change in config.json and run oac apply --discard-edits, which keeps the"
                           " edited copy as generated/<file>.edited-<time>. Nothing was applied.")
-    check_new_listeners(config, previous)
+    check_new_listeners(config, previous, disk, candidate)
     changed = [name for name, text in rendered.files.items() if disk.get(name) != text.encode()]
     removed = [name for name in (state.get("generated") or {}) if name not in rendered.files and disk.get(name) is not None]
 
@@ -677,7 +693,7 @@ def _apply(root, args, discard_edits, start, interactive, out, rollback=True, re
         (root / "secrets/core.key.new").unlink(missing_ok=True)
     if not (changed or removed or restarts or edited):
         if ingress_config.enabled(config):
-            finish_apply(root, config, state, rendered.files.get("Caddyfile"), will_run)
+            finish_apply(root, config, state, rendered.files.get("Caddyfile"), will_run, candidate)
         state = dict(state, core_installation_id=core_installation_id)
         if record_digests(state, rendered.files) != load_state(root):
             save_state(root, record_digests(state, rendered.files))
@@ -695,7 +711,7 @@ def _apply(root, args, discard_edits, start, interactive, out, rollback=True, re
         (root / "generated" / name).unlink()
     try:
         converge(root, state, rendered.services, will_run, force)
-        finish_apply(root, config, state, rendered.files.get("Caddyfile"), will_run)
+        finish_apply(root, config, state, rendered.files.get("Caddyfile"), will_run, candidate)
     except (OacError, RuntimeError, subprocess.CalledProcessError) as error:
         line = core_error_line(root, state)
         if line:
diff --git a/deploy/install/test_ingress.py b/deploy/install/test_ingress.py
index 3648c505b..f4266a051 100644
--- a/deploy/install/test_ingress.py
+++ b/deploy/install/test_ingress.py
@@ -29,6 +29,7 @@ def setUp(self):
             (ingress_config, "preflight", mock.Mock(return_value={"docker_socket": "/var/run/docker.sock", "docker_gid": 999})),
             (ingress_config, "reload", mock.Mock()),
             (ingress, "verify", mock.Mock()),
+            (ingress, "resolves", mock.Mock(return_value=True)),
         ):
             patch = mock.patch.object(owner, name, replacement)
             patch.start()
@@ -37,6 +38,9 @@ def setUp(self):
             run_installer(install, self.bundle, ["--install-dir", self.root, "--sandbox", "none"])
         self.host.recreated.clear()
 
+    def gateway_ports(self):
+        return json.loads((self.root / "generated/compose.json").read_text())["services"]["gateway"]["ports"]
+
     def test_default_bootstrap_then_https_reuses_installer_and_retains_data(self):
         config = oac_cli.load_config(self.root)
         self.assertEqual((config["host"], config["ingress"], config["public_url"]), ("0.0.0.0", "managed", None))
@@ -44,7 +48,7 @@ def test_default_bootstrap_then_https_reuses_installer_and_retains_data(self):
         self.assertEqual(services["core"]["ports"], ["127.0.0.1:8091:8091"])
         self.assertNotIn("ports", services["web"])
         self.assertNotIn("ports", services["database"])
-        self.assertIn("0.0.0.0:8080:8080", services["gateway"]["ports"])
+        self.assertEqual(services["gateway"]["ports"], ["0.0.0.0:8080:8080"])
         for name in ("core", "web"):
             self.assertNotIn("/docker.sock", str(services[name]))
         preserved = {name: (self.root / "secrets" / name).read_bytes()
@@ -52,7 +56,8 @@ def test_default_bootstrap_then_https_reuses_installer_and_retains_data(self):
         ingress.configure(self.root, "core.example.com", out=lambda _: None)
         self.assertEqual(ingress.status(self.root)["state"], "ready")
         self.assertEqual(oac_cli.load_config(self.root)["public_url"], "https://core.example.com")
-        self.assertEqual(set(self.host.recreated), {"core", "migrate", "web"})
+        self.assertEqual(set(self.host.recreated), {"core", "migrate", "web", "gateway"})
+        self.assertEqual(self.gateway_ports(), ["0.0.0.0:8080:8080", "0.0.0.0:80:80", "0.0.0.0:443:443"])
         self.assertIn("redir https://core.example.com{uri} 308", (self.root / "generated/Caddyfile").read_text())
         self.assertEqual(preserved, {name: (self.root / "secrets" / name).read_bytes() for name in preserved})
         self.host.recreated.clear()
@@ -70,11 +75,39 @@ def test_certificate_failure_keeps_http_and_retry_finishes(self):
         self.assertEqual((self.root / "config.json").read_bytes(), before)
         self.assertNotIn("redir", (self.root / "generated/Caddyfile").read_text())
         self.assertEqual(ingress.status(self.root)["state"], "failed")
-        self.assertEqual(self.host.recreated, [])
+        # The gateway published 80 and 443 for the attempt and was restored without them.
+        self.assertEqual(self.host.recreated, ["gateway", "gateway"])
+        self.assertEqual(self.gateway_ports(), ["0.0.0.0:8080:8080"])
         ingress.verify.side_effect = None
         ingress.configure(self.root, "core.example.com", out=lambda _: None)
         self.assertEqual(ingress.status(self.root)["state"], "ready")
 
+    def test_busy_https_port_refuses_setup_before_reserving_a_job(self):
+        self.host.busy.add(("0.0.0.0", 80))
+        before = (self.root / "ingress/status.json").read_bytes()
+        with self.assertRaises(ingress.DomainError) as error:
+            ingress.configure(self.root, "core.example.com", out=lambda _: None)
+        self.assertEqual((error.exception.code, error.exception.status), ("https_ports_unavailable", 409))
+        self.assertIn("Port 80 is already in use", str(error.exception))
+        self.assertEqual((self.root / "ingress/status.json").read_bytes(), before)
+        self.assertEqual((self.gateway_ports(), self.host.recreated), (["0.0.0.0:8080:8080"], []))
+
+    def test_unresolved_hostname_refuses_setup_before_reserving_a_job(self):
+        ingress.resolves.return_value = False
+        before = (self.root / "ingress/status.json").read_bytes()
+        with self.assertRaises(ingress.DomainError) as error:
+            ingress.configure(self.root, "core.example.com", out=lambda _: None)
+        self.assertEqual((error.exception.code, error.exception.status), ("hostname_unresolved", 409))
+        self.assertEqual((self.root / "ingress/status.json").read_bytes(), before)
+        self.assertEqual(self.host.recreated, [])
+
+    def test_domain_change_with_https_on_passes_its_own_port_check(self):
+        ingress.configure(self.root, "core.example.com", out=lambda _: None)
+        # The gateway itself now holds 80 and 443.
+        self.assertTrue({("0.0.0.0", 80), ("0.0.0.0", 443)} <= self.host.listening())
+        ingress.configure(self.root, "another.example.com", out=lambda _: None)
+        self.assertEqual(ingress.status(self.root)["public_url"], "https://another.example.com")
+
     def test_apply_failure_restores_previous_inputs_and_interruption_can_retry(self):
         self.host.core["rejects"] = lambda env: 'OAC_PUBLIC_URL="https://core.example.com"' in env
         with self.assertRaises(ingress.DomainError):
diff --git a/deploy/install/test_install.py b/deploy/install/test_install.py
index ce1d5c42b..1757ebb9e 100644
--- a/deploy/install/test_install.py
+++ b/deploy/install/test_install.py
@@ -16,6 +16,7 @@
 
 import config_model
 import distribution
+import ingress_config
 import install
 import node_spec
 from installer_fakes import MANIFEST, STANDARD_SIZES, FakeHost, make_bundle, run_installer
@@ -261,13 +262,20 @@ def test_taken_default_ports_move_to_the_next_free_port(self):
         self.assertIn("  Port 8080 was in use; Web uses 8081.\n", output)
         self.assertIn("  Port 8091 was in use; Core uses 8092.\n", output)
 
+    def test_managed_ingress_without_https_leaves_ports_80_and_443_alone(self):
+        self.host.busy.add(("0.0.0.0", 80))
+        with mock.patch.object(ingress_config, "preflight", return_value={"docker_socket": "/var/run/docker.sock", "docker_gid": 999}), \
+                mock.patch.object(ingress_config, "reload"), contextlib.redirect_stdout(self.output):
+            run_installer(install, self.bundle, ["--install-dir", self.root, "--sandbox", "none"])
+        self.assertEqual(self.document("generated/compose.json")["services"]["gateway"]["ports"], ["0.0.0.0:8080:8080"])
+
     def test_managed_https_needs_ports_80_and_443(self):
         self.host.busy.add(("0.0.0.0", 80))
         with contextlib.redirect_stdout(self.output), self.assertRaisesRegex(
                 install.InstallError, "^Automatic HTTPS needs ports 80 and 443, and port 80 is already in use on 0.0.0.0. "
                 "Free it, or use an existing reverse proxy with --ingress external; find the process with: "
                 "sudo ss -ltnp 'sport = :80'$"):
-            run_installer(install, self.bundle, ["--install-dir", self.root])
+            run_installer(install, self.bundle, ["--install-dir", self.root, "--public-url", "https://core.example"])
         self.assertFalse(self.root.exists())
 
     def test_output_labels_public_and_local_addresses(self):
@@ -285,6 +293,7 @@ def test_output_labels_public_and_local_addresses(self):
         }
         for name, (flags, expected) in cases.items():
             with self.subTest(name=name):
+                self.host.containers.clear()  # Each case installs on a host of its own.
                 self.root, self.output = self.work / name, io.StringIO()
                 self.install(*flags)
                 output = " ".join(self.output.getvalue().split())
diff --git a/docs/configuration.md b/docs/configuration.md
index 6c3c0be7c..bf3bc003d 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -20,7 +20,7 @@ The installer writes every setting that applies to the installation's [mode](get
 
 ### How oac apply works
 
-1. It validates `config.json` and changes nothing if a value is invalid. `mode`, `native_core` and `ingress` are fixed after installation; to change them, install into a new directory. It also checks the listeners that a changed `host` or port adds, and changes nothing if `host` is not an address of this machine or another program holds one of their ports; the installation's own listeners do not count.
+1. It validates `config.json` and changes nothing if a value is invalid. `mode`, `native_core` and `ingress` are fixed after installation; to change them, install into a new directory. It also checks the listeners that a changed `host`, port or managed-ingress `public_url` adds ([ports](getting-started/install-options.md#ports)), and changes nothing if `host` is not an address of this machine or another program holds one of their ports; the installation's own listeners do not count.
 2. It writes the files Core, Web and Compose read into `generated/`: `compose.json`, `core.env`, `core-key-digests.json`, `settings.json` and, when used, `runtime-history.json`, the managed `Caddyfile` and the native Core unit. Don't edit them. A generated file edited by hand stops `apply` until you move the change into `config.json` and run `oac apply --discard-edits`, which keeps the edited copy as `generated/<file>.edited-<time>`.
 3. It compares what it wrote with what actually runs. Each container carries a digest of its inputs (the `io.oac.inputs` label; native Core carries `OAC_INPUTS`), and `apply` recreates or restarts exactly the services whose inputs differ: Core first, then Web. The **Restarts** column below says which services a setting affects; see [stop and restart](getting-started/operations.md#stop-and-restart) for what a restart interrupts.
 4. While any service runs, `apply` also starts the stopped ones. After `oac stop`, it only writes the files and the installation stays stopped.
@@ -130,7 +130,7 @@ The installer creates the installation directory, `~/.oac/core` by default, with
 
 A Web-only installation has only `secrets/core.key`, a copy of its Core's key, and no `state/` or `native-installers/`. A Core-only installation has no `node-payload/`. Only managed ingress has `ingress/`. With native Core, the installation directory and the bundle must be canonical absolute paths without control characters, quotes, backslashes or wildcards.
 
-In Docker, the Compose project is named `oac-<10 hex digits>` (`project` in `state.json`). Its services are `database`, `migrate`, `core` and `web`, plus `gateway` and `installation` with managed ingress. `gateway` publishes `ports.web`, 80 and 443 and routes to Core and Web; `installation` applies domain changes from Web and uses the Docker socket to do so. The volume `<project>_database` holds all data. Native Core runs Core as the systemd user unit `<project>-core.service` instead of a container. Apart from Docker's storage, nothing is written outside your home directory.
+In Docker, the Compose project is named `oac-<10 hex digits>` (`project` in `state.json`). Its services are `database`, `migrate`, `core` and `web`, plus `gateway` and `installation` with managed ingress. `gateway` routes to Core and Web and publishes `ports.web`, plus [80 and 443](getting-started/install-options.md#ports) once HTTPS is on; `installation` applies domain changes from Web and uses the Docker socket to do so. The volume `<project>_database` holds all data. Native Core runs Core as the systemd user unit `<project>-core.service` instead of a container. Apart from Docker's storage, nothing is written outside your home directory.
 
 ## Appendix: Core environment without the installer
 
diff --git a/docs/getting-started/install-options.md b/docs/getting-started/install-options.md
index 7fd1f50de..2db7db5b2 100644
--- a/docs/getting-started/install-options.md
+++ b/docs/getting-started/install-options.md
@@ -46,7 +46,7 @@ These options choose an installation location or perform initial setup; they are
 | `--e2b-domain DOMAIN` | With E2B: sandbox data-plane DNS suffix; use together with `--e2b-api-url` |
 | `--core-key-file FILE` | With Web-only: absolute path to a private file containing the existing Core key, at least 32 characters |
 
-Several installations can share a machine when they use distinct installation directories and ports. Only one managed gateway can own ports 80 and 443 on an IP address; use distinct IP addresses or an external shared proxy for more. Each installation has its own database, Core key and nodes.
+Several installations can share a machine when they use distinct installation directories and ports. Only one installation with managed HTTPS can hold [ports 80 and 443](#ports) on an IP address; use distinct IP addresses or an external shared proxy for more. Each installation has its own database, Core key and nodes.
 
 ## Sandbox backend
 
@@ -72,7 +72,7 @@ Docker and microsandbox start at the Standard size in Web's [`standard-sizes.jso
 
 ## Listeners and access
 
-The default combined Docker installation selects `--ingress managed` and `--host 0.0.0.0`. Its gateway publishes Web on `--web-port` (8080 by default) and uses ports 80 and 443 for automatic HTTPS. Core's `--core-port` stays on loopback and PostgreSQL stays private. `--host` accepts IPv4 or IPv6, without a port, scheme or zone. Use a concrete server IP in the browser, not a wildcard. Managed ingress needs a local Docker Unix socket and Docker's ability to publish ports 80 and 443.
+The default combined Docker installation selects `--ingress managed` and `--host 0.0.0.0`. Its gateway publishes Web on `--web-port` (8080 by default), and [ports 80 and 443](#ports) once HTTPS is on. Core's `--core-port` stays on loopback and PostgreSQL stays private. `--host` accepts IPv4 or IPv6, without a port, scheme or zone. Use a concrete server IP in the browser, not a wildcard. Managed ingress needs a local Docker Unix socket.
 
 `--ingress external` uses your own reverse proxy instead. It is the only choice for Core-only, Web-only and native Core installations, and their default. Core and Web then listen on `--host`, loopback by default. External non-loopback listeners require an HTTPS `public_url` and a [reverse proxy](#https-and-the-reverse-proxy), and Web's domain setup is unavailable: set `public_url` in `config.json` and run `oac apply`.
 
@@ -80,14 +80,14 @@ The default combined Docker installation selects `--ingress managed` and `--host
 
 ### Ports
 
-Before it verifies the bundle or loads images, the installer checks `--host` and every port the installation will listen on: Web's and Core's, PostgreSQL's with native Core, and 80 and 443 with managed ingress.
+Before it verifies the bundle or loads images, the installer checks `--host` and every port the installation will listen on: Web's and Core's, PostgreSQL's with native Core, and 80 and 443 with managed ingress and `--public-url`.
 
 - `--host` must be an address of this machine, or a wildcard such as `0.0.0.0`.
 - A port set with `--web-port`, `--core-port` or in the `--config` file must be free, and so must a port that a loopback `--public-url` names, such as 8080 in `http://localhost:8080`. Otherwise the installer stops, names the port and prints the `ss` command that finds the program holding it.
 - A Web or Core port you leave out moves to the first free port above its default, at most 20 above, and never to another port of the same installation. The installer writes the chosen port to `config.json` and names it in the summary, for example `Port 8080 was in use; Web uses 8081.`
-- Managed ingress needs ports 80 and 443 and never moves them. If either is in use, free it, or install with `--ingress external` and use your own [reverse proxy](#https-and-the-reverse-proxy).
+- Managed ingress uses ports 80 and 443 only for HTTPS and never moves them. The gateway publishes them once `public_url` is set, from `--public-url` or [domain setup in Web](install.md#configure-the-domain-and-https), and no other program on the host may use them. If either is in use at installation, free it, install without `--public-url` and set up the domain later, or install with `--ingress external` and use your own [reverse proxy](#https-and-the-reverse-proxy).
 
-After installation, `oac apply` [checks the ports](../configuration.md#how-oac-apply-works) of a changed `host` or port.
+After installation, `oac apply` [checks the ports](../configuration.md#how-oac-apply-works) of a changed `host` or port, and 80 and 443 when `public_url` turns HTTPS on. Domain setup in Web and `oac domain` check, before they start, that the hostname resolves and that no other program holds port 80 or 443, and name the port that is in use.
 
 ## HTTPS and the reverse proxy
 
diff --git a/docs/getting-started/install.md b/docs/getting-started/install.md
index 98bfe7521..aab86a7e2 100644
--- a/docs/getting-started/install.md
+++ b/docs/getting-started/install.md
@@ -17,7 +17,7 @@ This page follows the default path. Every flag, existing reverse proxies, split
 - Linux amd64 with Python 3.9 or newer, and curl. No GitHub account or CLI is needed.
 - Docker Engine with Docker Compose 2.26.0 or newer (`docker compose version`).
 - An account that can run `docker` and write to its home directory. Ordinary users and root both work; the installer never calls sudo.
-- Free ports 80 and 443 for HTTPS, and a port each for initial Web access (8080) and Core (8091, on loopback); see [ports](install-options.md#ports). Docker must be able to publish them; the installer does not change host policy.
+- A free port each for initial Web access (8080) and Core (8091, on loopback), and free ports 80 and 443 once you turn on HTTPS; see [ports](install-options.md#ports). Docker must be able to publish them; the installer does not change host policy.
 - A DNS hostname that points to this host, before you connect applications, nodes, E2B or self-hosted machines. You can install and sign in first.
 
 The Core host needs no KVM; nodes that run microsandbox do.
@@ -56,10 +56,10 @@ It creates no Project or key and makes no model request. It ends by printing the
 
 Applications, nodes and sandboxes reach Core at one HTTPS address, the public URL. The initial HTTP address serves only Web.
 
-1. Point the hostname's A/AAAA records to this host, and allow inbound ports 80 and 443 from the internet.
+1. Point the hostname's A/AAAA records to this host, allow inbound ports 80 and 443 from the internet, and keep other programs off [those ports](install-options.md#ports).
 2. In Web, open **System**, choose **Configure domain and HTTPS**, enter the hostname, such as `core.example.com`, and choose **Apply**.
 
-The installation requests a certificate and checks that the HTTPS address reaches this installation before switching Core and Web to it. Then open the HTTPS address and sign in again; the initial HTTP address redirects there. Certificates renew automatically. If DNS or the certificate fails, the previous address stays in use: correct the reported problem and retry. Retry an interrupted switch with the same hostname, or check it with `oac status` and finish it with `oac apply`.
+The installation checks DNS and the ports, requests a certificate and checks that the HTTPS address reaches this installation before switching Core and Web to it. Then open the HTTPS address and sign in again; the initial HTTP address redirects there. Certificates renew automatically. If DNS or the certificate fails, the previous address stays in use: correct the reported problem and retry. Retry an interrupted switch with the same hostname, or check it with `oac status` and finish it with `oac apply`.
 
 The same operation from a terminal:
 
diff --git a/docs/getting-started/operations.md b/docs/getting-started/operations.md
index d7209c8db..c8d971eb3 100644
--- a/docs/getting-started/operations.md
+++ b/docs/getting-started/operations.md
@@ -155,7 +155,7 @@ The installer and mutating `oac` commands hold the same installation lock, `.oac
 | `Docker Compose 2.26.0 or newer is required …` | Update the Docker Compose plugin |
 | `Port N (…) is already in use on ADDRESS …` | Another program holds a port the installation needs. Find it with the printed `ss` command and stop it, or choose another port: `--web-port` or `--core-port` at [installation](install-options.md#ports), or the port in `config.json` before `oac apply` |
 | `ADDRESS (…) is not an address of this machine …` | Set `--host`, or `host` in `config.json`, to one of the machine's IP addresses or a wildcard such as `0.0.0.0` |
-| `Automatic HTTPS needs ports 80 and 443 …` | Free the port the message names, or install with `--ingress external` and use your own [reverse proxy](install-options.md#https-and-the-reverse-proxy) |
+| `Automatic HTTPS needs ports 80 and 443 …` | Free the port the message names, install without `--public-url` and set up the domain later, or install with `--ingress external` and use your own [reverse proxy](install-options.md#https-and-the-reverse-proxy) |
 | `Installation directory is not empty …` | Use an empty `--install-dir` |
 | `This installation is configured by …/config.json …` | Flags only seed a new installation: edit `config.json` and run `oac apply` |
 | `This installation version or historical conversion is not supported …` | The target directory holds an installation of another release, or a default install found one at `~/.parsar/core`. Keep it, and install into another empty `--install-dir` ([version policy](#installation-version-policy)) |
@@ -163,7 +163,8 @@ The installer and mutating `oac` commands hold the same installation lock, `.oac
 | `config.json has changes that are not applied` | Run `oac apply` |
 | `Core rejects secrets/core.key …` | Run `oac apply`, which restarts Core with the key's digest |
 | `config.json not applied: …` | `oac apply` printed Core's startup error above; fix `config.json` and apply again |
-| `HTTPS verification failed …` during domain setup | See [Configure the domain and HTTPS](install.md#configure-the-domain-and-https) |
+| `Port 80 is already in use on this server …` during domain setup | Another program holds port 80 or 443. Stop it, using the printed `ss` command to find it, and retry; automatic HTTPS cannot share [these ports](install-options.md#ports) |
+| `HTTPS verification failed …` during domain setup | DNS points elsewhere, a firewall or NAT blocks inbound ports 80 and 443, or the certificate request failed; see [Configure the domain and HTTPS](install.md#configure-the-domain-and-https) |
 | Web answers 403 `Forbidden` | Open exactly the console address `oac status` prints; a reverse proxy must pass the original Host |
 | `/v1` or `/api/v1` answers 404 | Those paths reach Web; route them to Core ([reverse proxy](install-options.md#https-and-the-reverse-proxy)) |
 | Web shows that Core is unavailable (502) | Core is stopped or failing: `oac status`, then Core's log |
@@ -175,7 +176,7 @@ The installer and mutating `oac` commands hold the same installation lock, `.oac
 
 | Listener | Managed ingress (default) | External ingress |
 | --- | --- | --- |
-| Web | Reached only through the `gateway` service, which publishes `ports.web` (8080), 80 and 443 on `host` (all IPv4 interfaces by default) | `host:ports.web` (loopback by default), behind your reverse proxy |
+| Web | Reached only through the `gateway` service, which publishes `ports.web` (8080) on `host` (all IPv4 interfaces by default), plus [80 and 443](install-options.md#ports) once HTTPS is on | `host:ports.web` (loopback by default), behind your reverse proxy |
 | Core | `127.0.0.1:ports.core` (8091); the gateway routes `/v1` and `/api/v1` to it | `host:ports.core`, behind your reverse proxy |
 | PostgreSQL | No published port | No published port, or a loopback port with native Core |
 

From 54c5151e063793126aeb91d8f8340d5bce4be491 Mon Sep 17 00:00:00 2001
From: SaladDay <1203511142@qq.com>
Date: Wed, 30 Sep 2026 08:58:57 +0000
Subject: [PATCH 2/2] Confirm domain changes from the applied address and
 harden retries

Domain setup returns Core to the applied address before it switches, so
prepare confirms a public URL change from there, and the final apply makes
the change prepare confirmed. A retry after a switch interrupted with Core
already on the new address no longer fails after verification.

The written gateway ports count as the installation's own only while the
gateway runs with the written inputs. oac start keeps an unfinished domain
setup recorded, so its status reports the interruption, and that message
says what oac apply does. A failure in the candidate apply reaches Web as
the domain setup message. DNS resolves the hostname as an absolute name.
The interrupted-retry test now stops the switch itself, before and after
Core restarts.
---
 deploy/install/README.md           |  2 +-
 deploy/install/ingress.py          | 36 ++++++++++++++++++++++--------
 deploy/install/oac_cli.py          | 28 +++++++++++++----------
 deploy/install/test_ingress.py     | 17 +++++++++++---
 docs/getting-started/operations.md |  2 +-
 5 files changed, 59 insertions(+), 26 deletions(-)

diff --git a/deploy/install/README.md b/deploy/install/README.md
index abf3c8f18..93fc86806 100644
--- a/deploy/install/README.md
+++ b/deploy/install/README.md
@@ -66,7 +66,7 @@ This directory holds the Core/Web installer, the `oac` command and the node inst
 A default combined Docker installation adds two Compose services from one pinned image: `gateway` runs Caddy, and `installation` runs the packaged `oac domain-server`. The latter runs with the installing account's UID and its Docker socket access and calls the same locked apply implementation. Its only request surface is the private `ingress/api/api.sock`, with Core-key authentication and one typed domain action. Core and Web get no Docker socket, host process authority or writable installation configuration. Web gets only the private API socket directory, never Caddy's admin socket.
 
 - The gateway publishes the initial Web port, and ports 80 and 443 only for HTTPS (`ingress_config.published`). Caddy issues and renews certificates and keeps its private data in `ingress/data`. `generated/Caddyfile` is derived from `config.json`, and apply reloads it through the private Caddy socket even when container inputs already match.
-- A domain change first checks that the hostname resolves and that no other program holds port 80 or 443; ports the written gateway already publishes are its own. It keeps the old entry point while the common apply renders the candidate address: the gateway publishes 80 and 443 and serves the candidate, and the verification needs a trusted certificate and an installation-specific response over HTTPS. Only then does it set `public_url` and apply again. Failure restores the previous configuration, including the gateway without 80 and 443 when HTTPS was off, and reports incomplete recovery; failed retries restore through the common apply even after a partial change.
+- A domain change first checks that the hostname resolves and that no other program holds port 80 or 443; ports the gateway publishes while it runs as written are its own. It confirms a public URL change from the applied address, because it returns Core there before switching. It keeps the old entry point while the common apply renders the candidate address: the gateway publishes 80 and 443 and serves the candidate, and the verification needs a trusted certificate and an installation-specific response over HTTPS. Only then does it set `public_url` and apply again. Failure restores the previous configuration, including the gateway without 80 and 443 when HTTPS was off, and reports incomplete recovery; failed retries restore through the common apply even after a partial change.
 - The operation record keeps the last successfully applied public address. Apply and start update it after gateway verification and service health checks; generated files alone never prove that a new address is active. A successful apply reconciles the domain operation status after verifying the running services.
 - The domain operation refuses unrelated pending `config.json` edits and shares `.oac.lock` with the CLI. Its status file is bookkeeping and the recovery receipt; `config.json` stays the source of desired settings. An interrupted operation keeps its desired files and a visible failure and retry state; it never creates another service project or deletes execution data.
 - A Web restart ends console sessions, so the UI gives the new HTTPS sign-in address instead of treating a dropped request as success.
diff --git a/deploy/install/ingress.py b/deploy/install/ingress.py
index 109a1ad77..bff1b8c31 100644
--- a/deploy/install/ingress.py
+++ b/deploy/install/ingress.py
@@ -19,6 +19,10 @@
 import oac_cli
 
 
+FAILED = "Domain setup failed. Check gateway and installation logs, then retry."
+UNFINISHED = ("checking", "applying")
+
+
 class DomainError(oac_cli.OacError):
     def __init__(self, code, message, status=400):
         super().__init__(message)
@@ -29,6 +33,12 @@ def save(root, value):
     oac_cli.write_private(Path(root) / "ingress/status.json", json.dumps(value) + "\n")
 
 
+def unfinished(root):
+    """Whether status.json records a domain setup that has not finished."""
+    path = Path(root) / "ingress/status.json"
+    return path.exists() and json.loads(oac_cli.read_private(path, "domain setup status"))["state"] in UNFINISHED
+
+
 def status(root):
     config = oac_cli.load_config(root)
     supported = gateway.enabled(config)
@@ -41,14 +51,14 @@ def status(root):
         path = Path(root) / "ingress/status.json"
         if path.exists():
             result.update(json.loads(oac_cli.read_private(path, "domain setup status")))
-            if result["state"] in ("checking", "applying"):
+            if result["state"] in UNFINISHED:
                 try:
                     with oac_cli.locked(Path(root)):
                         # A live CLI or Web operation holds this same lock. Read
                         # again after acquiring it in case the operation just finished.
                         result.update(json.loads(oac_cli.read_private(path, "domain setup status")))
-                        if result["state"] in ("checking", "applying"):
-                            result.update(state="failed", message="Domain setup was interrupted. Retry the same hostname, or run oac apply and oac status on the server.")
+                        if result["state"] in UNFINISHED:
+                            result.update(state="failed", message="Domain setup was interrupted. Retry the same hostname, or run oac apply on the server: it restores the applied address, or finishes the switch if it had started.")
                 except oac_cli.OacError:
                     pass
     return result
@@ -89,16 +99,20 @@ def prepare(root, name, confirmation):
     if not resolves(host):
         raise DomainError("hostname_unresolved", f"{host} does not resolve. Add A/AAAA records for it that point at this server, then retry when DNS returns them.", 409)
     # The gateway publishes 80 and 443 only for HTTPS; the ports it already publishes are its own.
-    busy = [str(listener.port) for listener in oac_cli.taken_listeners(candidate, oac_cli.own_listeners(config, old_settings, disk))]
+    busy = [str(listener.port) for listener in oac_cli.taken_listeners(candidate, oac_cli.own_listeners(config, old_settings, disk, actual))]
     if busy:
         named = f"Port {busy[0]} is" if len(busy) == 1 else "Ports " + " and ".join(busy) + " are"
         raise DomainError("https_ports_unavailable", f"{named} already in use on this server. Automatic HTTPS cannot run beside another program on ports 80 and 443: free both and retry. Find the program with: sudo ss -ltnp '( sport = :80 or sport = :443 )'", 409)
-    old, base, answered = oac_cli.old_public_url(root, config, old_settings, disk, actual)
+    _, base, answered = oac_cli.old_public_url(root, config, old_settings, disk, actual)
     args = argparse.Namespace(dry_run=False, yes=False, confirm_public_url_change=confirmation)
     try:
-        oac_cli.confirm_public_url(root, candidate, old, base, answered, args, False, lambda _: None)
+        # execute returns Core to the applied address first, even after an interrupted switch,
+        # so the change is confirmed from there.
+        oac_cli.confirm_public_url(root, candidate, configuration.local_public_url(config), base, answered, args, False, lambda _: None)
     except oac_cli.OacError:
         raise DomainError("public_url_confirmation_required", "Changing this address can disconnect existing nodes and executors. Confirm the new URL to continue; retain the old route while existing work uses it.", 409) from None
+    # The final apply makes the change confirmed here.
+    args = argparse.Namespace(dry_run=False, yes=False, confirm_public_url_change=target)
     job = {"state": "checking", "target_url": target, "public_url": config["public_url"], "message": None}
     save(root, job)
     return config, state, candidate, args, job
@@ -107,7 +121,8 @@ def prepare(root, name, confirmation):
 def resolves(host):
     """Whether DNS answers with an A or AAAA record."""
     try:
-        return bool(socket.getaddrinfo(host, 443, type=socket.SOCK_STREAM))
+        # The trailing dot keeps the resolver from appending its search domains.
+        return bool(socket.getaddrinfo(host + ".", 443, type=socket.SOCK_STREAM))
     except (OSError, UnicodeError):
         return False
 
@@ -139,7 +154,10 @@ def execute(root, prepared):
     try:
         # Through common apply, the gateway publishes 80 and 443 and serves the candidate.
         oac_cli.write_private(Path(root) / "config.json", json.dumps(config, indent=2) + "\n")
-        oac_cli._apply(Path(root), keep, False, False, False, lambda _: None, candidate=candidate["public_url"])
+        try:
+            oac_cli._apply(Path(root), keep, False, False, False, lambda _: None, candidate=candidate["public_url"])
+        except oac_cli.OacError:
+            raise DomainError("domain_setup_failed", FAILED) from None  # Its message addresses oac apply users.
         verify(candidate["public_url"], state["installation_id"])
         job["state"] = "applying"
         save(root, job)
@@ -159,7 +177,7 @@ def execute(root, prepared):
             gateway.reload(root, gateway.caddyfile(config, state))
         except Exception:
             recovery_failed = True
-        message = str(error) if isinstance(error, (DomainError, oac_cli.OacError)) else "Domain setup failed. Check gateway and installation logs, then retry."
+        message = str(error) if isinstance(error, (DomainError, oac_cli.OacError)) else FAILED
         if recovery_failed:
             message += " Recovery was incomplete; run oac apply and oac status on the server."
         job.update(state="failed", message=message)
diff --git a/deploy/install/oac_cli.py b/deploy/install/oac_cli.py
index d7c52f107..5ee47e10e 100644
--- a/deploy/install/oac_cli.py
+++ b/deploy/install/oac_cli.py
@@ -581,12 +581,15 @@ def check_paired_core(root, config, state, previous, args, interactive, out):
     return installation
 
 
-def own_listeners(config, previous, disk):
+def own_listeners(config, previous, disk, actual):
     """(address, port) of this installation's listeners: those of the settings last written, and
-    those of the written gateway, which domain setup widens before public_url changes."""
+    those of the gateway, which domain setup widens before public_url changes, while it runs as written."""
     applied = applied_view(config, previous)
-    return ({(ipaddress.ip_address(listener.host), listener.port) for listener in configuration.listeners(applied)}
-            | ingress_config.written_listeners(disk.get("compose.json")))
+    own = {(ipaddress.ip_address(listener.host), listener.port) for listener in configuration.listeners(applied)}
+    gateway = actual.get("gateway", {})
+    if gateway.get("running") and gateway.get("inputs") == configuration.rendered_inputs(disk, None).get("gateway"):
+        own |= ingress_config.written_listeners(disk.get("compose.json"))
+    return own
 
 
 def taken_listeners(config, own, candidate=None):
@@ -596,7 +599,7 @@ def taken_listeners(config, own, candidate=None):
             and not port_free(listener.host, listener.port, own)]
 
 
-def check_new_listeners(config, previous, disk, candidate=None):
+def check_new_listeners(config, previous, disk, actual, candidate=None):
     """Each listener this change adds must be free; this installation's own listeners do not count."""
     if previous is None:
         return
@@ -604,13 +607,14 @@ def check_new_listeners(config, previous, disk, candidate=None):
     if config["host"] != applied["host"] and not address_available(config["host"]):
         raise OacError(f"{config['host']} (host) is not an address of this machine; use one of its addresses. "
                        "Nothing was applied.")
-    taken = taken_listeners(config, own_listeners(config, previous, disk), candidate)
+    taken = taken_listeners(config, own_listeners(config, previous, disk, actual), candidate)
     if taken:
         raise OacError(port_in_use(taken[0], taken[0].setting, " Nothing was applied."))
 
 
-def finish_apply(root, config, state, gateway_document, will_run, candidate=None):
-    """With a candidate, domain setup verifies it and records its own status."""
+def finish_apply(root, config, state, gateway_document, will_run, candidate=None, keep_unfinished=False):
+    """With a candidate, domain setup verifies it and records its own status. keep_unfinished
+    leaves an unfinished domain setup recorded, so its status reports the interruption."""
     managed = ingress_config.enabled(config) and "gateway" in will_run
     if managed:
         import ingress
@@ -619,7 +623,7 @@ def finish_apply(root, config, state, gateway_document, will_run, candidate=None
         if config["public_url"] and not candidate:
             ingress.verify(config["public_url"], state["installation_id"])
     health(root, config, will_run)
-    if managed and not candidate:
+    if managed and not candidate and not (keep_unfinished and ingress.unfinished(root)):
         ingress.save(root, {"state": "ready" if config["public_url"] else "unconfigured",
                             "public_url": config["public_url"], "target_url": config["public_url"], "message": None})
 
@@ -647,11 +651,11 @@ def _apply(root, args, discard_edits, start, interactive, out, rollback=True, re
         raise OacError("\n".join(f"generated/{name} was edited by hand." for name in edited)
                           + "\nPut the change in config.json and run oac apply --discard-edits, which keeps the"
                           " edited copy as generated/<file>.edited-<time>. Nothing was applied.")
-    check_new_listeners(config, previous, disk, candidate)
+    actual = observe(state)
+    check_new_listeners(config, previous, disk, actual, candidate)
     changed = [name for name, text in rendered.files.items() if disk.get(name) != text.encode()]
     removed = [name for name in (state.get("generated") or {}) if name not in rendered.files and disk.get(name) is not None]
 
-    actual = observe(state)
     running = {name for name, item in actual.items() if item["running"] and name != "migrate"}
     will_run = (set(rendered.services) - {"migrate"}) if (start or running) else set()
     todo = stale(actual, rendered.services, will_run)
@@ -878,7 +882,7 @@ def start(root, out=print):
         will_run = set(desired) - {"migrate"}
         converge(root, state, desired, will_run)
         gateway_document = (root / "generated/Caddyfile").read_text() if ingress_config.enabled(written) else None
-        finish_apply(root, written, state, gateway_document, will_run)
+        finish_apply(root, written, state, gateway_document, will_run, keep_unfinished=True)
     out("Services started.")
 
 
diff --git a/deploy/install/test_ingress.py b/deploy/install/test_ingress.py
index f4266a051..d26a3c41d 100644
--- a/deploy/install/test_ingress.py
+++ b/deploy/install/test_ingress.py
@@ -201,19 +201,30 @@ def test_status_requires_both_managed_ingress_services(self):
 
     def test_failed_retry_restores_the_receipt_before_and_after_service_convergence(self):
         before = (self.root / "generated/core.env").read_bytes()
+        self.host.bindings["self_hosted_executors"] = 1
+        target = "https://core.example.com"
         converge = oac_cli.converge
         for restarted in (False, True):
             with self.subTest(services_restarted=restarted):
+                calls = []
                 def interrupt(*args, **kwargs):
-                    if restarted:
+                    # The gateway converges for the candidate; the switch stops before or after converging.
+                    calls.append(args)
+                    if len(calls) == 1 or restarted:
                         converge(*args, **kwargs)
-                    raise KeyboardInterrupt()
+                    if len(calls) == 2:
+                        raise KeyboardInterrupt()
                 with mock.patch.object(oac_cli, "converge", side_effect=interrupt), self.assertRaises(KeyboardInterrupt):
+                    ingress.configure(self.root, "core.example.com", target, out=lambda _: None)
+                self.assertEqual(len(calls), 2)
+                # The retry returns Core to the applied address first, so it confirms the change from there.
+                with self.assertRaises(ingress.DomainError) as error:
                     ingress.configure(self.root, "core.example.com", out=lambda _: None)
+                self.assertEqual(error.exception.code, "public_url_confirmation_required")
                 ingress_config.reload.reset_mock()
                 ingress.verify.side_effect = ingress.DomainError("https_not_ready", "DNS not ready")
                 with self.assertRaisesRegex(ingress.DomainError, "DNS not ready"):
-                    ingress.configure(self.root, "core.example.com", out=lambda _: None)
+                    ingress.configure(self.root, "core.example.com", target, out=lambda _: None)
                 for call in ingress_config.reload.call_args_list:
                     self.assertNotIn("redir", call.args[1])
                 self.assertIsNone(oac_cli.load_config(self.root)["public_url"])
diff --git a/docs/getting-started/operations.md b/docs/getting-started/operations.md
index c8d971eb3..8eabf4e32 100644
--- a/docs/getting-started/operations.md
+++ b/docs/getting-started/operations.md
@@ -163,7 +163,7 @@ The installer and mutating `oac` commands hold the same installation lock, `.oac
 | `config.json has changes that are not applied` | Run `oac apply` |
 | `Core rejects secrets/core.key …` | Run `oac apply`, which restarts Core with the key's digest |
 | `config.json not applied: …` | `oac apply` printed Core's startup error above; fix `config.json` and apply again |
-| `Port 80 is already in use on this server …` during domain setup | Another program holds port 80 or 443. Stop it, using the printed `ss` command to find it, and retry; automatic HTTPS cannot share [these ports](install-options.md#ports) |
+| `… already in use on this server. Automatic HTTPS cannot run beside another program …` during domain setup | Another program holds port 80 or 443. Stop it, using the printed `ss` command to find it, and retry; automatic HTTPS cannot share [these ports](install-options.md#ports) |
 | `HTTPS verification failed …` during domain setup | DNS points elsewhere, a firewall or NAT blocks inbound ports 80 and 443, or the certificate request failed; see [Configure the domain and HTTPS](install.md#configure-the-domain-and-https) |
 | Web answers 403 `Forbidden` | Open exactly the console address `oac status` prints; a reverse proxy must pass the original Host |
 | `/v1` or `/api/v1` answers 404 | Those paths reach Web; route them to Core ([reverse proxy](install-options.md#https-and-the-reverse-proxy)) |