fix(hosted): name the ingress network on routed runtime services (#30)

Coolify puts every routed container on two networks: the application network
that carries the ingress proxy, and the private runtime network its peers
address. Traefik reads a container's address from the first network it iterates
when no network is named, and Go randomises that order, so about half of the
routed services were resolved to their 172.29.x runtime address after every
proxy configuration rebuild and answered nothing on their public route.
Restarting one container reshuffled the choice for all of them.

Name the network explicitly on the twelve routed services that join both.
Coolify exports the application uuid into the environment it runs Compose in,
and names the proxy-carrying network after it, so the label resolves without a
new operator-set variable and fails the deployment loudly if it is ever absent.

Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>

Author: jeremi

compose.coolify.agriculture.yaml

@@ -31,7 +31,7 @@ services:
     command: [serve, --runtime, /etc/relay/nagdi/runtime.yaml]
     environment: {SOLMARA_RELAY_AUDIT_KEY: "${NAGDI_RELAY_AUDIT_KEY:?required}", SOLMARA_RELAY_CURSOR_KEY: "${NAGDI_RELAY_CURSOR_KEY:?required}"}
     volumes: [/data/solmara-authority-cells/nagdi-relay/runtime:/etc/relay/nagdi:ro, /data/solmara-authority-cells/nagdi-relay/source:/var/lib/relay/source:ro, nagdi-relay-audit:/var/lib/relay/audit]
-    labels: {solmara.lab.host: nagdi-relay-authority-cells.solmara.registrystack.org, solmara.rollout.slot: authority-cells}
+    labels: {solmara.lab.host: nagdi-relay-authority-cells.solmara.registrystack.org, solmara.rollout.slot: authority-cells, traefik.docker.network: "${COOLIFY_RESOURCE_UUID:?set by Coolify for every deployment}"}
 
   nagdi-evidence:
     <<: *runtime
@@ -42,7 +42,7 @@ services:
     depends_on:
       audit-permissions: {condition: service_completed_successfully}
       nagdi-relay: {condition: service_started}
-    labels: {solmara.lab.host: "${SOLMARA_NAGDI_EVIDENCE_PUBLIC_HOST:-nagdi-evidence.solmara.registrystack.org}", solmara.rollout.slot: authority-cells}
+    labels: {solmara.lab.host: "${SOLMARA_NAGDI_EVIDENCE_PUBLIC_HOST:-nagdi-evidence.solmara.registrystack.org}", solmara.rollout.slot: authority-cells, traefik.docker.network: "${COOLIFY_RESOURCE_UUID:?set by Coolify for every deployment}"}
 
 volumes:
   nagdi-relay-audit:

compose.coolify.interior.yaml

@@ -31,15 +31,15 @@ services:
     command: [serve, --runtime, /etc/relay/cra/runtime.yaml]
     environment: {SOLMARA_RELAY_AUDIT_KEY: "${CRA_RELAY_AUDIT_KEY:?required}"}
     volumes: [/data/solmara-authority-cells/cra-relay/runtime:/etc/relay/cra:ro, /data/solmara-authority-cells/cra-relay/source:/var/lib/relay/source:ro, cra-relay-audit:/var/lib/relay/audit]
-    labels: {solmara.lab.host: cra-relay-authority-cells.solmara.registrystack.org, solmara.rollout.slot: authority-cells}
+    labels: {solmara.lab.host: cra-relay-authority-cells.solmara.registrystack.org, solmara.rollout.slot: authority-cells, traefik.docker.network: "${COOLIFY_RESOURCE_UUID:?set by Coolify for every deployment}"}
 
   nia-relay:
     <<: *runtime
     image: ${REGISTRY_RELAY_IMAGE:?set the digest-pinned official Registry Stack Relay image}
     command: [serve, --runtime, /etc/relay/nia/runtime.yaml]
     environment: {SOLMARA_RELAY_AUDIT_KEY: "${NIA_RELAY_AUDIT_KEY:?required}"}
     volumes: [/data/solmara-authority-cells/nia-relay/runtime:/etc/relay/nia:ro, /data/solmara-authority-cells/nia-relay/source:/var/lib/relay/source:ro, nia-relay-audit:/var/lib/relay/audit]
-    labels: {solmara.lab.host: nia-relay-authority-cells.solmara.registrystack.org, solmara.rollout.slot: authority-cells}
+    labels: {solmara.lab.host: nia-relay-authority-cells.solmara.registrystack.org, solmara.rollout.slot: authority-cells, traefik.docker.network: "${COOLIFY_RESOURCE_UUID:?set by Coolify for every deployment}"}
 
   cra-evidence:
     <<: *runtime
@@ -50,15 +50,15 @@ services:
     depends_on:
       audit-permissions: {condition: service_completed_successfully}
       cra-relay: {condition: service_started}
-    labels: {solmara.lab.host: "${SOLMARA_CRA_EVIDENCE_PUBLIC_HOST:-cra-evidence.solmara.registrystack.org}", solmara.rollout.slot: authority-cells}
+    labels: {solmara.lab.host: "${SOLMARA_CRA_EVIDENCE_PUBLIC_HOST:-cra-evidence.solmara.registrystack.org}", solmara.rollout.slot: authority-cells, traefik.docker.network: "${COOLIFY_RESOURCE_UUID:?set by Coolify for every deployment}"}
 
   nia-evidence:
     <<: *runtime
     image: ${SOLMARA_EVIDENCE_IMAGE:?set the digest-pinned official Registry Stack Evidence image}
     command: [--runtime, /etc/registry-evidence/nia/runtime.yaml, serve]
     volumes: [/data/solmara-authority-cells/nia-evidence/runtime:/etc/registry-evidence/nia:ro, /data/solmara-authority-cells/nia-evidence/secrets:/run/secrets/registry-evidence/nia:ro, /data/solmara-authority-cells/nia-evidence/transit:/run/registry-evidence/nia:ro, /data/solmara-authority-cells/nia-evidence/extracts:/var/lib/registry-evidence/nia/extracts:ro, nia-evidence-audit:/var/lib/registry-evidence/nia/audit]
     networks: {runtime: {ipv4_address: 172.29.2.22}}
-    labels: {solmara.lab.host: "${SOLMARA_NIA_EVIDENCE_PUBLIC_HOST:-nia-evidence.solmara.registrystack.org}", solmara.rollout.slot: authority-cells}
+    labels: {solmara.lab.host: "${SOLMARA_NIA_EVIDENCE_PUBLIC_HOST:-nia-evidence.solmara.registrystack.org}", solmara.rollout.slot: authority-cells, traefik.docker.network: "${COOLIFY_RESOURCE_UUID:?set by Coolify for every deployment}"}
 
 volumes:
   cra-relay-audit:

compose.coolify.labour-pensions.yaml

@@ -31,7 +31,7 @@ services:
     command: [serve, --runtime, /etc/relay/sipf/runtime.yaml]
     environment: {SOLMARA_RELAY_AUDIT_KEY: "${SIPF_RELAY_AUDIT_KEY:?required}", SOLMARA_RELAY_CURSOR_KEY: "${SIPF_RELAY_CURSOR_KEY:?required}"}
     volumes: [/data/solmara-authority-cells/sipf-relay/runtime:/etc/relay/sipf:ro, /data/solmara-authority-cells/sipf-relay/source:/var/lib/relay/source:ro, sipf-relay-audit:/var/lib/relay/audit]
-    labels: {solmara.lab.host: sipf-relay-authority-cells.solmara.registrystack.org, solmara.rollout.slot: authority-cells}
+    labels: {solmara.lab.host: sipf-relay-authority-cells.solmara.registrystack.org, solmara.rollout.slot: authority-cells, traefik.docker.network: "${COOLIFY_RESOURCE_UUID:?set by Coolify for every deployment}"}
 
   sipf-evidence:
     <<: *runtime
@@ -42,7 +42,7 @@ services:
     depends_on:
       audit-permissions: {condition: service_completed_successfully}
       sipf-relay: {condition: service_started}
-    labels: {solmara.lab.host: "${SOLMARA_SIPF_EVIDENCE_PUBLIC_HOST:-sipf-evidence.solmara.registrystack.org}", solmara.rollout.slot: authority-cells}
+    labels: {solmara.lab.host: "${SOLMARA_SIPF_EVIDENCE_PUBLIC_HOST:-sipf-evidence.solmara.registrystack.org}", solmara.rollout.slot: authority-cells, traefik.docker.network: "${COOLIFY_RESOURCE_UUID:?set by Coolify for every deployment}"}
 
 volumes:
   sipf-relay-audit:

compose.coolify.social-development.yaml

@@ -31,15 +31,15 @@ services:
     command: [serve, --runtime, /etc/relay/mosd/runtime.yaml]
     environment: {SOLMARA_RELAY_AUDIT_KEY: "${MOSD_RELAY_AUDIT_KEY:?required}"}
     volumes: [/data/solmara-authority-cells/mosd-relay/runtime:/etc/relay/mosd:ro, /data/solmara-authority-cells/mosd-relay/source:/var/lib/relay/source:ro, mosd-relay-audit:/var/lib/relay/audit]
-    labels: {solmara.lab.host: mosd-programme-relay-authority-cells.solmara.registrystack.org, solmara.rollout.slot: authority-cells}
+    labels: {solmara.lab.host: mosd-programme-relay-authority-cells.solmara.registrystack.org, solmara.rollout.slot: authority-cells, traefik.docker.network: "${COOLIFY_RESOURCE_UUID:?set by Coolify for every deployment}"}
 
   sro-evidence:
     <<: *runtime
     image: ${SOLMARA_EVIDENCE_IMAGE:?set the digest-pinned official Registry Stack Evidence image}
     command: [--runtime, /etc/registry-evidence/sro/runtime.yaml, serve]
     volumes: [/data/solmara-authority-cells/sro-evidence/runtime:/etc/registry-evidence/sro:ro, /data/solmara-authority-cells/sro-evidence/secrets:/run/secrets/registry-evidence/sro:ro, /data/solmara-authority-cells/sro-evidence/transit:/run/registry-evidence/sro:ro, /data/solmara-authority-cells/sro-evidence/extracts:/var/lib/registry-evidence/sro/extracts:ro, sro-evidence-audit:/var/lib/registry-evidence/sro/audit]
     networks: {runtime: {ipv4_address: 172.29.3.23}}
-    labels: {solmara.lab.host: "${SOLMARA_SRO_EVIDENCE_PUBLIC_HOST:-sro-evidence.solmara.registrystack.org}", solmara.rollout.slot: authority-cells}
+    labels: {solmara.lab.host: "${SOLMARA_SRO_EVIDENCE_PUBLIC_HOST:-sro-evidence.solmara.registrystack.org}", solmara.rollout.slot: authority-cells, traefik.docker.network: "${COOLIFY_RESOURCE_UUID:?set by Coolify for every deployment}"}
 
   mosd-programme-evidence:
     <<: *runtime
@@ -50,7 +50,7 @@ services:
     depends_on:
       audit-permissions: {condition: service_completed_successfully}
       mosd-relay: {condition: service_started}
-    labels: {solmara.lab.host: "${SOLMARA_MOSD_PROGRAMME_EVIDENCE_PUBLIC_HOST:-mosd-programme-evidence.solmara.registrystack.org}", solmara.rollout.slot: authority-cells}
+    labels: {solmara.lab.host: "${SOLMARA_MOSD_PROGRAMME_EVIDENCE_PUBLIC_HOST:-mosd-programme-evidence.solmara.registrystack.org}", solmara.rollout.slot: authority-cells, traefik.docker.network: "${COOLIFY_RESOURCE_UUID:?set by Coolify for every deployment}"}
 
 volumes:
   mosd-relay-audit:

compose.coolify.yaml

@@ -36,7 +36,7 @@ services:
     networks: {runtime: {ipv4_address: 172.29.1.20}}
     depends_on:
       audit-permissions: {condition: service_completed_successfully}
-    labels: {solmara.lab.host: mint-authority-cells.solmara.registrystack.org, solmara.rollout.slot: authority-cells}
+    labels: {solmara.lab.host: mint-authority-cells.solmara.registrystack.org, solmara.rollout.slot: authority-cells, traefik.docker.network: "${COOLIFY_RESOURCE_UUID:?set by Coolify for every deployment}"}
   mint-readiness:
     image: ${SOLMARA_AUTHORITY_PROVISIONER_IMAGE:?set the digest-pinned Solmara authority provisioner image}
     entrypoint: [python, -c]

docs/hosted-deployment.md

@@ -75,6 +75,17 @@ runtime requires before it accepts a wildcard bind. Isolation rests on network
 membership rather than on the bind address: an application's networks carry only
 its own containers and the proxy, so no authority reaches another's cells.
 
+Joining two networks makes a container's routable address ambiguous. Traefik
+reads the address from the first network it iterates when no network is named,
+and that order is randomised, so an unnamed service is routed to its private
+runtime address on roughly half of every proxy configuration rebuild and then
+answers nothing on its public route. Every routed service that joins the runtime
+network therefore carries
+`traefik.docker.network: ${COOLIFY_RESOURCE_UUID:?set by Coolify for every deployment}`,
+which resolves to the Coolify-managed network the proxy is on. A routed service
+that joins the ingress network alone has no choice to remove and carries no such
+label.
+
 `compose.coolify.provision.yaml` is a dedicated operator-only application. It
 runs only the one-shot target provisioners and is the sole writer of every
 shared path except the seven Transit sockets.

scripts/check-coolify-compose.sh

@@ -10,6 +10,7 @@ scratch=$(mktemp -d)
 trap 'rm -rf -- "$scratch"' EXIT HUP INT TERM
 
 check_compose() {
+  COOLIFY_RESOURCE_UUID=solmara-test-application \
   REGISTRY_RELAY_IMAGE="ghcr.io/registrystack/relay@sha256:$test_digest" \
   SOLMARA_EVIDENCE_IMAGE="$test_image" \
   SOLMARA_MINT_IMAGE="$test_image" \

scripts/test_hosted_evidence_routes.py

@@ -72,6 +72,9 @@
 
 def compose_environment() -> dict[str, str]:
     environment = os.environ | {
+        # Coolify exports this into the environment it runs Compose in, and the
+        # routed services read it to name the network the ingress proxy is on.
+        "COOLIFY_RESOURCE_UUID": "test-application-uuid",
         "SOLMARA_AUTHORITY_PROVISIONER_IMAGE": TEST_IMAGE,
         "REGISTRY_RELAY_IMAGE": TEST_IMAGE,
         "SOLMARA_EVIDENCE_IMAGE": TEST_IMAGE,

scripts/test_hosted_network_isolation.py

@@ -30,6 +30,9 @@
 # application's networks contain another application's containers, so binding
 # every interface reaches only the owning application and the proxy.
 BIND_HOST = "0.0.0.0"
+# Coolify exports the application uuid into the environment it runs Compose in,
+# and names the network that carries the ingress proxy after it.
+INGRESS_NETWORK = "${COOLIFY_RESOURCE_UUID:?set by Coolify for every deployment}"
 PROVISIONED_SERVICES = {
     "mint-provisioner": ("core", "mint", "172.29.1.20"),
     "cra-evidence-provisioner": ("interior", "cra-evidence", "172.29.2.21"),
@@ -107,6 +110,32 @@ def test_provisioned_services_keep_distinct_addresses_in_their_subnet(self) -> N
             )
             addresses[expected_address] = service_name
 
+    def test_routed_services_on_the_runtime_network_name_the_ingress_network(
+        self,
+    ) -> None:
+        """Traefik reads a container's address from the first network it iterates
+        when no network is named, and that order is randomised, so a service that
+        joins both the runtime network and the ingress network is routed to its
+        private runtime address on roughly half of every proxy configuration
+        rebuild and then answers nothing. Naming the ingress network removes the
+        choice. A service that joins the ingress network alone has no choice to
+        remove, so it carries no label."""
+        pinned = 0
+        for app, compose in self.runtime.items():
+            for service_name, service in compose["services"].items():
+                labels = service.get("labels") or {}
+                if "solmara.lab.host" not in labels:
+                    continue
+                where = f"{app}/{service_name}"
+                if "runtime" not in (service.get("networks") or {}):
+                    self.assertNotIn("traefik.docker.network", labels, where)
+                    continue
+                self.assertEqual(
+                    labels.get("traefik.docker.network"), INGRESS_NETWORK, where
+                )
+                pinned += 1
+        self.assertEqual(pinned, 12)
+
     def test_provisioning_services_remain_networkless(self) -> None:
         self.assertNotIn("networks", self.provision)
         for service_name, service in self.provision["services"].items():