Refactor environment configuration and enhance NGINX setup for Keycloak integration

Author: mcqueide

.env.example

@@ -5,42 +5,8 @@ COMPOSE_PROJECT_NAME=people
 ENVIRONMENT=production
 
 # ----------------------------------------------------------------------------
-# API DB
+# POSTGRES ADMIN
+# For compose file variable substitution like ${POSTGRES_USER} and ${POSTGRES_DB}
 # ----------------------------------------------------------------------------
-POSTGRES_DB=people
-POSTGRES_USER=postgres
-POSTGRES_PASSWORD_FILE=/run/secrets/db-password
-PGDATA=/var/lib/postgresql/data/pgdata
-POSTGRES_INITDB_ARGS=--encoding=UTF-8 --lc-collate=C --lc-ctype=C
-
-# ----------------------------------------------------------------------------
-# KEYCLOAK ADMIN (Web UI credentials)
-# ----------------------------------------------------------------------------
-KC_DB=postgres
-KC_DB_URL=jdbc:postgresql://db:5432/keycloak
-KC_DB_USERNAME=keycloak
-KC_DB_PASSWORD=keycloak
-KC_HOSTNAME=keycloak.example.com
-KC_PROXY_HEADERS=xforwarded
-KC_BOOTSTRAP_ADMIN_USERNAME=username
-KC_BOOTSTRAP_ADMIN_PASSWORD=password
-KC_HEALTH_ENABLED=true
-KC_METRICS_ENABLED=true
-
-# ----------------------------------------------------------------------------
-# SPRING
-# ----------------------------------------------------------------------------
-SPRING_PROFILES_ACTIVE=docker
-SPRING_DATASOURCE_URL=jdbc:postgresql://db:5432/people
-SPRING_DATASOURCE_USERNAME=username
-SPRING_DATASOURCE_PASSWORD=password
-#JAVA_OPTS="-XX:+UseG1GC -Xms256m -Xmx512m"
-JAVA_OPTS="-XX:+UseG1GC -XX:MaxRAMPercentage=75"
-KEYCLOAK_ISSUER_URI=http://keycloak.example.com/realms/people-realm
-KEYCLOAK_JWK_SET_URI=http://keycloak.example.com/realms/people-realm/protocol/openid-connect/certs
-
-# ----------------------------------------------------------------------------
-# NGINX
-# ----------------------------------------------------------------------------
-NGINX_PORT=80
-NGINX_SSL_PORT=443
+POSTGRES_DB=postgres
+POSTGRES_USER=postgres

.gitignore

@@ -34,8 +34,13 @@ build/
 
 ### Docker ###
 .env
+.env.api
+.env.db
+.env.keycloak
+.env.nginx
 secrets/*.txt
 
+
 ### Kubernetes ###
 values.y*ml
 secret.y*ml

compose.yaml

@@ -138,6 +138,22 @@ volumes:
     labels:
       description: "Spring Boot application logs"
 
+  # Volume for Keycloak data (build configuration and cache)
+  keycloak-conf:
+    driver: local
+    labels:
+      description: "Keycloak build configuration"
+      backup: "recommended"
+      critical: "false"
+
+  # Volume for Keycloak runtime data (cache, temporary files)
+  keycloak-lib:
+    driver: local
+    labels:
+      description: "Keycloak runtime data"
+      backup: "recommended"
+      critical: "false"
+
 # ============================================================================
 # SECRETS
 # ============================================================================
@@ -170,7 +186,7 @@ services:
   nginx:
     image: nginx:1.29-alpine
     container_name: nginx
-    
+
     # Drop all capabilities (principle of least privilege)
     cap_drop:
       - ALL
@@ -184,6 +200,9 @@ services:
     security_opt:
       - no-new-privileges:true # Prevent escalation
 
+    env_file:
+      - env_files/.env.nginx
+
     # Restart policy
     restart: unless-stopped
 
@@ -268,6 +287,9 @@ services:
     networks:
       - backend
 
+    extra_hosts:
+      - "mcqueide.local:172.21.0.1"
+
     # Ports: DO NOT expose externally in production
     # ports:
     #   - "8081:8080"  # ❌ For debug only, remove in production
@@ -276,9 +298,8 @@ services:
     expose:
       - "8080"
 
-    # Not required, docker uses .env by default
     env_file:
-      - .env
+      - env_files/.env.api
 
     secrets:
       - api-db-password
@@ -383,7 +404,7 @@ services:
 
     # Not required, docker uses .env by default
     env_file:
-      - .env
+      - env_files/.env.db
 
     # OPTIMIZATION: Use tmpfs for temporary data (improves performance)
     # Sockets and temp files don't require persistence
@@ -393,7 +414,7 @@ services:
 
     # Healthcheck
     healthcheck:
-      test: [ "CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}" ]
+      test: [ "CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-postgres} -d ${POSTGRES_DB:-postgres}" ]
       interval: 10s
       timeout: 5s
       retries: 5
@@ -455,11 +476,15 @@ services:
       - keycloak-admin-password
 
     env_file:
-      - .env
+      - env_files/.env.keycloak
 
     volumes:
+      - keycloak-conf:/opt/keycloak/conf
+      - keycloak-lib:/opt/keycloak/lib/quarkus/
       - ./keycloak/export:/opt/keycloak/data/import
 
+    # NOTE: Use 'start' for production (builds automatically on first run)
+    # After first successful build, you can optionally use 'start --optimized' for faster restarts
     command: start-dev
 
     # Run import
@@ -470,7 +495,7 @@ services:
         condition: service_healthy
 
     healthcheck:
-      test: ["CMD-SHELL", "exec 3<>/dev/tcp/keycloak/9000 && echo -e 'GET /health/ready HTTP/1.1\r\nHost: keycloak\r\nConnection: close\r\n\r\n' >&3 && cat <&3 | grep -q '200 OK'"]
+      test: ["CMD-SHELL", "exec 3<>/dev/tcp/keycloak/9000 && echo -e 'GET /auth/health/ready HTTP/1.1\r\nHost: keycloak\r\nConnection: close\r\n\r\n' >&3 && cat <&3 | grep -q '200 OK'"]
       interval: 30s
       timeout: 10s
       retries: 5
@@ -480,10 +505,10 @@ services:
       resources:
         limits:
           cpus: '0.5'
-          memory: 512M
+          memory: 768M
         reservations:
           cpus: '0.25'
-          memory: 256M
+          memory: 512M
 
     logging:
       driver: "json-file"
@@ -513,7 +538,7 @@ services:
       - keycloak-admin-password
 
     env_file:
-      - .env
+      - env_files/.env.keycloak
 
     volumes:
       - ./keycloak/export:/opt/keycloak/data/import:rw
@@ -543,10 +568,6 @@ services:
 # Deploy with minimal downtime:
 #   docker compose up -d --no-deps --build app
 #
-# Check service health:
-#   docker compose ps
-#   docker compose exec app node healthcheck.js
-#
 # Logs:
 #   docker compose logs -f app
 #   docker compose logs --tail=100 postgres

env_files/.env.api.example

@@ -0,0 +1,13 @@
+# ----------------------------------------------------------------------------
+# SPRING
+# ----------------------------------------------------------------------------
+SPRING_PROFILES_ACTIVE=docker
+SPRING_DATASOURCE_URL=jdbc:postgresql://db:5432/people
+SPRING_DATASOURCE_USERNAME=people
+SPRING_DATASOURCE_PASSWORD=people
+#JAVA_OPTS="-XX:+UseG1GC -Xms256m -Xmx512m"
+JAVA_OPTS="-XX:+UseG1GC -XX:MaxRAMPercentage=75"
+CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:4200,http://app:3000,http://keycloak:8080
+CORS_ALLOWCREDENTIALS=true
+KEYCLOAK_ISSUER_URI=http://keycloak:8080/auth/realms/people-realm
+KEYCLOAK_CLIENT_SECRET=  # Empty for public client with PKCE

env_files/.env.db.example

@@ -0,0 +1,6 @@
+# ----------------------------------------------------------------------------
+# POSTGRES ADMIN
+# ----------------------------------------------------------------------------
+POSTGRES_DB=postgres
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD_FILE=/run/secrets/db-password

env_files/.env.keycloak.example

@@ -0,0 +1,19 @@
+# ----------------------------------------------------------------------------
+# KEYCLOAK ADMIN (Web UI credentials)
+# ----------------------------------------------------------------------------
+KC_DB=postgres
+KC_DB_URL=jdbc:postgresql://db:5432/keycloak
+KC_DB_USERNAME=keycloak
+KC_DB_PASSWORD=keycloak
+KC_HOSTNAME=keycloak
+#KC_HOSTNAME=localhost # If Keycloak is accessed only locally
+# KC_PROXY=edge # Deprecated
+KC_PROXY_HEADERS=xforwarded
+KC_HOSTNAME_STRICT=false # To allow access via HTTP instead of HTTPS, not recommended for production.
+KC_HTTP_ENABLED=true
+KC_BOOTSTRAP_ADMIN_USERNAME=admin
+KC_BOOTSTRAP_ADMIN_PASSWORD=admin
+KC_HEALTH_ENABLED=true
+KC_METRICS_ENABLED=true
+KC_LOG_LEVEL=info
+KC_HTTP_RELATIVE_PATH=/auth

env_files/.env.nginx.example

@@ -0,0 +1,5 @@
+# ----------------------------------------------------------------------------
+# NGINX
+# ----------------------------------------------------------------------------
+NGINX_PORT=80
+NGINX_SSL_PORT=443

nginx/conf.d/default.conf

@@ -32,9 +32,58 @@ server {
         add_header Content-Type text/plain;
     }
 
+    # ========================================================================
+    # KEYCLOAK - Identity and Access Management
+    # ========================================================================
+    location ^~ /auth/ {
+        limit_req zone=general burst=30 nodelay;
+        limit_conn addr 15;
+
+        proxy_pass http://keycloak;
+        proxy_http_version 1.1;
+        
+        # Essential headers for Keycloak behind reverse proxy
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Host $host;
+        proxy_set_header X-Forwarded-Port $server_port;
+        
+        # Buffer settings for Keycloak admin console
+        proxy_buffering on;
+        proxy_buffer_size 8k;
+        proxy_buffers 8 8k;
+        
+        # Timeouts (Keycloak can be slow on first start)
+        proxy_connect_timeout 60s;
+        proxy_send_timeout 60s;
+        proxy_read_timeout 60s;
+        
+        proxy_set_header Connection "";
+    }
+
     # ========================================================================
     # BACKEND API ROUTES
     # ========================================================================
+    location /swagger-ui.html {
+        limit_req zone=general burst=20 nodelay;
+        limit_conn addr 10;
+
+        proxy_pass http://backend;
+        proxy_http_version 1.1;
+        
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        
+        proxy_connect_timeout 30s;
+        proxy_send_timeout 30s;
+        proxy_read_timeout 30s;
+        proxy_set_header Connection "";
+    }
+    
     location /swagger-ui/ {
         limit_req zone=general burst=20 nodelay;
         limit_conn addr 10;

nginx/nginx.conf

@@ -97,6 +97,19 @@ http {
         keepalive_timeout 60s;
     }
 
+    # ========================================================================
+    # UPSTREAM - Keycloak
+    # ========================================================================
+    upstream keycloak {
+        least_conn;
+        
+        server keycloak:8080 max_fails=3 fail_timeout=30s weight=1;
+        
+        keepalive 32;
+        keepalive_requests 100;
+        keepalive_timeout 60s;
+    }
+
     # ========================================================================
     # UPSTREAM - Frontend App (Node.js)
     # ========================================================================

src/main/resources/application.yml

@@ -43,7 +43,7 @@ spring:
             jwk-set-uri: ${issuer-uri}/protocol/openid-connect/certs
             user-name-attribute: preferred_username
 
-issuer-uri: ${KEYCLOAK_ISSUER_URI:http://localhost:8080/realms/people-realm}
+issuer-uri: ${KEYCLOAK_ISSUER_URI:http://localhost:8080/auth/realms/people-realm}
 
 # CORS Configuration
 cors:
@@ -94,4 +94,4 @@ spring:
 server:
   port: 8080
 
-issuer-uri: ${KEYCLOAK_ISSUER_URI:http://keycloak:8080/realms/people-realm}
+issuer-uri: ${KEYCLOAK_ISSUER_URI:http://keycloak:8080/auth/realms/people-realm}