From 4d54440ac9e30ae950378cb80d5e0b1e93a0365a Mon Sep 17 00:00:00 2001
From: danc094codetogether <daniel@codetogether.com>
Date: Thu, 5 Mar 2026 14:27:51 -0600
Subject: [PATCH 1/2] Add dedicated Keycloak readiness gate to prevent Intel
 starting too early

This PR adds an optional Docker Compose overlay that supports customers running a dedicated/external Keycloak (Keycloak not started by our compose stack).

Some customers still use an external Keycloak. In this mode, the previously recommended depends_on: codetogether-keycloak: condition: service_healthy cannot apply, because there is no codetogether-keycloak service in the final stack. As a result, docker compose up --wait can fail because codetogether-intel starts before Keycloak is reachable.

Add a new compose overlay: compose/compose.dedicated-keycloak.yaml

Introduces a lightweight keycloak-ready service with a healthcheck that polls:
https://${KEYCLOAK_FQDN}/realms/${KEYCLOAK_REALM}/.well-known/openid-configuration

Makes codetogether-intel depend on:

- cassandra: service_healthy (keep existing dependency)
- keycloak-ready: service_healthy (new gate)

- Add a short compose/README.md describing:
- required .env variables (KEYCLOAK_FQDN, KEYCLOAK_REALM)
- exact docker compose command using the overlay

docker compose \
  -f compose/compose.yaml \
  -f compose/compose.dedicated-keycloak.yaml \
  --env-file ./.env \
  up --pull always --wait -d
---
 compose/compose.dedicated-keycloak.yaml | 25 ++++++++++++++++++++++++
 compose/dedicated-keycloak.md           | 26 +++++++++++++++++++++++++
 2 files changed, 51 insertions(+)
 create mode 100644 compose/compose.dedicated-keycloak.yaml
 create mode 100644 compose/dedicated-keycloak.md

diff --git a/compose/compose.dedicated-keycloak.yaml b/compose/compose.dedicated-keycloak.yaml
new file mode 100644
index 0000000..fcf030f
--- /dev/null
+++ b/compose/compose.dedicated-keycloak.yaml
@@ -0,0 +1,25 @@
+services:
+  # Readiness gate for dedicated/external Keycloak.
+  # Intel will wait until the realm OIDC metadata endpoint responds successfully.
+  keycloak-ready:
+    image: curlimages/curl:8.6.0
+    command: ["sh", "-lc", "sleep infinity"]
+    healthcheck:
+      test: ["CMD-SHELL", "curl -fsS https://${KEYCLOAK_FQDN}/realms/${KEYCLOAK_REALM}/.well-known/openid-configuration > /dev/null || exit 1"]
+      interval: 5s
+      timeout: 3s
+      retries: 60
+      start_period: 10s
+    networks:
+      - codetogethernet
+
+  codetogether-intel:
+    depends_on:
+      cassandra:
+        condition: service_healthy
+      keycloak-ready:
+        condition: service_healthy
+
+networks:
+  codetogethernet:
+    external: true
\ No newline at end of file
diff --git a/compose/dedicated-keycloak.md b/compose/dedicated-keycloak.md
new file mode 100644
index 0000000..fa1c0a4
--- /dev/null
+++ b/compose/dedicated-keycloak.md
@@ -0,0 +1,26 @@
+# Dedicated / External Keycloak: startup gate for Intel
+
+If Keycloak is **not** started by Docker Compose (dedicated/external Keycloak), Intel may start too early.
+Use the overlay `compose.dedicated-keycloak.yaml` to make Intel wait until Keycloak is reachable.
+
+## Required `.env` entries
+
+Add these to the root `.env` (same directory you pass via `--env-file`):
+
+```dotenv
+KEYCLOAK_FQDN=<KEYCLOAK_FQDN>
+KEYCLOAK_REALM=<REALM>
+```
+
+`KEYCLOAK_REALM` must match the realm used in your OIDC URLs:
+`https://<KEYCLOAK_FQDN>/realms/<REALM>/...`
+
+## Run
+
+```bash
+docker compose \
+  -f compose/compose.yaml \
+  -f compose/compose.dedicated-keycloak.yaml \
+  --env-file ./.env \
+  up --pull always --wait -d
+```
\ No newline at end of file

From 7dc6dddd83f261208805c6aab0668f2b4566bd6f Mon Sep 17 00:00:00 2001
From: danc094codetogether <daniel@codetogether.com>
Date: Thu, 5 Mar 2026 16:19:05 -0600
Subject: [PATCH 2/2] Fix

---
 compose/dedicated-keycloak.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/compose/dedicated-keycloak.md b/compose/dedicated-keycloak.md
index fa1c0a4..c578175 100644
--- a/compose/dedicated-keycloak.md
+++ b/compose/dedicated-keycloak.md
@@ -1,5 +1,7 @@
 # Dedicated / External Keycloak: startup gate for Intel
 
+This overlay assumes you already have a Keycloak instance running outside of Docker Compose.
+
 If Keycloak is **not** started by Docker Compose (dedicated/external Keycloak), Intel may start too early.
 Use the overlay `compose.dedicated-keycloak.yaml` to make Intel wait until Keycloak is reachable.