Normalize GeoIP host binding for Railway

Author: Rieranthony

apps/geoip/.env.default

@@ -1,6 +1,6 @@
 # GeoIP service
 GEOIP_DB_DIR=/data/geoip
-HOST=::
+HOST=0.0.0.0
 PORT=8080
 
 # Local API -> GeoIP service

apps/geoip/README.md

@@ -30,7 +30,7 @@ MAXMIND_LICENSE_KEY=<secret>
 MAXMIND_EDITION_IDS=GeoLite2-City GeoLite2-ASN
 GEOIP_DB_DIR=/data/geoip
 GEOIP_UPDATE_INTERVAL_HOURS=24
-HOST=::
+HOST=0.0.0.0
 PORT=8080
 ```
 
@@ -59,7 +59,7 @@ GEOIP_SERVICE_URL=http://localhost:8083
 
 Deploy this app as its own Railway service named `geoip`.
 
-The service uses Hypercorn and binds both `0.0.0.0` and `::` by default so Railway's public deployment healthchecks and private networking can both reach it.
+The service uses Hypercorn and binds to `0.0.0.0` by default. Wildcard values like `HOST=::` are normalized to the same single bind so Linux container runtimes do not fail with `address already in use`.
 
 Use `/live` as the Railway deployment healthcheck path. `/health` remains a readiness endpoint and can return `503` until the MaxMind databases have been downloaded and loaded.
 
@@ -70,7 +70,7 @@ The service now starts serving `/live` immediately while the initial MaxMind boo
 - `current_update_started_at`: when the active update began
 - `last_update_error`: the latest refresh/bootstrap failure, if any
 
-Railway environment variable values should be entered as raw values without wrapping quotes. For example, use `HOST=::`, not `HOST="::"`.
+Railway environment variable values should be entered as raw values without wrapping quotes. For example, use `HOST=0.0.0.0`, not `HOST="0.0.0.0"`.
 
 Railway logs will now include `geoipupdate` output, which makes it easier to confirm whether the MaxMind databases are actively downloading.
 

apps/geoip/src/config.py

@@ -49,7 +49,7 @@ def from_env(cls) -> "Settings":
 			license_key=os.getenv("MAXMIND_LICENSE_KEY", "").strip(),
 			edition_ids=_split_edition_ids(os.getenv("MAXMIND_EDITION_IDS")),
 			db_dir=Path(os.getenv("GEOIP_DB_DIR", "/data/geoip")),
-			host=os.getenv("HOST", "::").strip() or "::",
+			host=os.getenv("HOST", "0.0.0.0").strip() or "0.0.0.0",
 			update_interval_hours=int(os.getenv("GEOIP_UPDATE_INTERVAL_HOURS", "24")),
 			port=int(os.getenv("PORT", "8080")),
 		)

apps/geoip/src/main.py

@@ -38,8 +38,10 @@ async def initialize_databases(manager: GeoIPDatabaseManager) -> None:
 
 def build_bind_addresses(host: str, port: int) -> list[str]:
 	normalized_host = host.strip()
-	if not normalized_host or normalized_host == "::":
-		return [f"0.0.0.0:{port}", f"[::]:{port}"]
+	# Binding both 0.0.0.0 and [::] can conflict on Linux when the IPv6 socket
+	# also accepts IPv4 traffic. Normalize wildcard hosts to a single safe bind.
+	if not normalized_host or normalized_host in {"::", "0.0.0.0"}:
+		return [f"0.0.0.0:{port}"]
 
 	if ":" in normalized_host and not normalized_host.startswith("["):
 		return [f"[{normalized_host}]:{port}"]

apps/geoip/tests/test_main.py

@@ -122,8 +122,13 @@ def test_live_returns_200_while_initialization_is_still_running() -> None:
 	assert health_response.json()["update_in_progress"] is True
 
 
-def test_build_bind_addresses_defaults_to_dual_stack_for_railway() -> None:
-	assert build_bind_addresses("::", 8080) == ["0.0.0.0:8080", "[::]:8080"]
+def test_build_bind_addresses_normalizes_wildcard_hosts_to_single_bind() -> None:
+	assert build_bind_addresses("::", 8080) == ["0.0.0.0:8080"]
+	assert build_bind_addresses("0.0.0.0", 8080) == ["0.0.0.0:8080"]
+
+
+def test_build_bind_addresses_preserves_explicit_ipv6_host() -> None:
+	assert build_bind_addresses("2001:db8::1", 8080) == ["[2001:db8::1]:8080"]
 
 
 def test_lookup_returns_payload() -> None: