feat(dev): allow running e2e in a custom Docker network

Author: azasypkin

Makefile

@@ -1,6 +1,7 @@
 COMPOSE_DEV          	:= dev/docker/docker-compose.yml
 COMPOSE_DEBUG_SCRAPER	:= dev/docker/docker-compose.debug-scraper.yml
 COMPOSE_E2E          	:= dev/docker/docker-compose.e2e.yml
+COMPOSE_EXTERNAL_NET 	:= dev/docker/docker-compose.external-network.yml
 ENV_FILE             	:= .env
 CHROME_PATH          	?= /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
 RUNS                 	?= 10
@@ -59,11 +60,16 @@ scraper: ## Run web scraper on host (headed browser).
 
 ## ---------- End-to-End Testing ----------
 
-e2e-up: ## Start the full e2e stack (all services in Docker). Use BUILD=1 to rebuild images.
-	docker compose -f $(COMPOSE_DEV) -f $(COMPOSE_E2E) --env-file $(ENV_FILE) up $(if $(BUILD),--build) -d
+COMPOSE_E2E_FILES := -f $(COMPOSE_DEV) -f $(COMPOSE_E2E)
+ifdef EXTERNAL_NETWORK
+  COMPOSE_E2E_FILES += -f $(COMPOSE_EXTERNAL_NET)
+endif
+
+e2e-up: ## Start the full e2e stack (all services in Docker). Use BUILD=1 to rebuild images. Use EXTERNAL_NETWORK=<name> to join an external Docker network.
+	docker compose $(COMPOSE_E2E_FILES) --env-file $(ENV_FILE) up $(if $(BUILD),--build) -d
 
 e2e-down: ## Stop the e2e stack and remove volumes.
-	docker compose -f $(COMPOSE_DEV) -f $(COMPOSE_E2E) --env-file $(ENV_FILE) down --volumes --remove-orphans
+	docker compose $(COMPOSE_E2E_FILES) --env-file $(ENV_FILE) down --volumes --remove-orphans
 
 e2e-test: ## Run Playwright e2e tests (use ARGS for extra flags, e.g. make e2e-test ARGS="--ui").
 	cd e2e && npx playwright test $(ARGS)
@@ -91,7 +97,7 @@ e2e-report: ## Open the Playwright HTML report.
 	cd e2e && npx playwright show-report
 
 e2e-logs: ## Tail logs from e2e stack.
-	docker compose -f $(COMPOSE_DEV) -f $(COMPOSE_E2E) logs -f
+	docker compose $(COMPOSE_E2E_FILES) logs -f
 
 ## ---------- Documentation ----------
 

dev/docker/docker-compose.e2e.yml

@@ -70,7 +70,7 @@ services:
       context: ../..
       dockerfile: Dockerfile.webui
     ports:
-      - "7171:8080"
+      - "7171:7171"
     volumes:
       - type: bind
         source: ./nginx-e2e.conf

dev/docker/docker-compose.external-network.yml

@@ -0,0 +1,34 @@
+# Optional overlay: join secutils_webui (nginx) to an external Docker network so that
+# containers on that network can reach webhook responders by subdomain hostname.
+#
+# Uses *.webhooks.secutils.local instead of *.webhooks.localhost because *.localhost
+# resolves to 127.0.0.1 inside containers (RFC 6761), bypassing Docker DNS aliases.
+# A companion nginx config translates the host back to *.webhooks.localhost for the API.
+#
+# Usage:
+#   make e2e-up EXTERNAL_NETWORK=retrack
+#   make e2e-up EXTERNAL_NETWORK=retrack WEBHOOK_ALIAS=abc-docs.webhooks.secutils.local
+#
+# Then from a container on the external network:
+#   curl http://docs.webhooks.secutils.local:7171/my-path
+services:
+  secutils_api:
+    networks:
+      net: {}
+      external_net: {}
+
+  secutils_webui:
+    networks:
+      net: {}
+      external_net:
+        aliases:
+          - "${WEBHOOK_ALIAS:-docs.webhooks.secutils.local}"
+    volumes:
+      - type: bind
+        source: ./nginx-external-network.conf
+        target: /etc/nginx/conf.d/external-network.conf
+
+networks:
+  external_net:
+    external: true
+    name: ${EXTERNAL_NETWORK}

dev/docker/nginx-e2e.conf

@@ -1,7 +1,7 @@
 # Webhook subdomain routing - mirrors Traefik IngressRoute in production.
 server {
-    listen       8080;
-    listen  [::]:8080;
+    listen       7171;
+    listen  [::]:7171;
     server_name  ~^(.+)\.webhooks\.localhost$;
 
     location / {
@@ -18,8 +18,8 @@ server {
 }
 
 server {
-    listen       8080 default_server;
-    listen  [::]:8080 default_server;
+    listen       7171 default_server;
+    listen  [::]:7171 default_server;
     server_name  localhost;
 
     client_max_body_size 50m;

dev/docker/nginx-external-network.conf

@@ -0,0 +1,21 @@
+# Webhook subdomain routing for containers on an external Docker network.
+#
+# *.localhost hostnames resolve to 127.0.0.1 inside containers (RFC 6761), so Docker
+# network aliases must use a different suffix. This server block accepts requests on
+# *.webhooks.secutils.local and translates them to the X-Forwarded-Host that the API
+# expects (*.webhooks.localhost).
+server {
+    listen       7171;
+    listen  [::]:7171;
+    server_name  ~^(?<webhook_subdomain>.+)\.webhooks\.secutils\.local$;
+
+    location / {
+        set $original_uri $uri;
+        rewrite ^ /api/webhooks break;
+        proxy_pass http://secutils_api:7070;
+        proxy_set_header X-Forwarded-Host $webhook_subdomain.webhooks.localhost;
+        proxy_set_header X-Replaced-Path $original_uri;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    }
+}