keycloak-api-manager 4.0.0 → 5.0.0

package/test/docker-keycloak/DEPLOYMENT_GUIDE.md

@@ -1,262 +0,0 @@
-# Keycloak Deployment Setup Guide
-
-## Quick Start
-
-### Local HTTP (Development)
-```bash
-npm run setup-keycloak
-# Select: 1 (Local)
-# Select: 1 (HTTP)
-# ✓ Keycloak accessible at http://localhost:8080
-```
-
-### Local HTTPS (Production-like)
-```bash
-npm run setup-keycloak
-# Select: 1 (Local)
-# Select: 2 (HTTPS)
-# 
-# If certificates exist in test/docker-keycloak/certs:
-#   ✓ Script automatically uses them
-# 
-# Otherwise, enter certificate path when prompted:
-#   Certificate directory path: /path/to/certs
-#   (or press Enter to use default location)
-# 
-# ✓ Keycloak accessible at https://localhost:8443
-```
-
-### Remote HTTP
-```bash
-npm run setup-keycloak
-# Choose deployment: Remote (auto-selected, no Docker locally)
-# Enable HTTPS: 1 (No - HTTP)
-# Remote host/IP: smart@smart-dell-sml.crs4.it
-# ✓ Keycloak deployed at http://smart-dell-sml.crs4.it:8080
-```
-
-### Remote HTTPS
-```bash
-npm run setup-keycloak
-# Choose deployment: Remote (auto-selected)
-# Enable HTTPS: 2 (Yes - HTTPS)
-# → Certificates automatically loaded from: test/docker-keycloak/certs
-# Remote host/IP: smart@smart-dell-sml.crs4.it
-# ✓ Certificates copied to remote and deployed with HTTPS
-# ✓ Keycloak accessible at https://smart-dell-sml.crs4.it:8443
-```
-
-## Features
-
-### ✅ Local Deployment
-- **HTTP Mode**: Development environment, no certificates needed
-- **HTTPS Mode**: Production-like environment using SSL/TLS certificates
-- **Automatic Health Checks**: Waits for Keycloak to be fully ready
-- **Docker Integration**: Uses docker-compose for easy container management
-
-### ✅ Remote Deployment via SSH
-- **Automatic File Transfer**: Copies docker-compose files via SCP
-- **Certificate Management**: Copies certificates to remote server if HTTPS enabled
-- **SSH Connectivity**: Verifies SSH connection before deployment
-- **Health Checks**: Confirms Keycloak is running on remote server
-
-### ✅ Configuration Management
-- **.env Files**: Auto-generated configuration files
-- **Certificate Mounting**: Automatic mounting of SSL certificates
-- **Hostname Configuration**: Sets proper KEYCLOAK_HOSTNAME for remote servers
-- **Port Configuration**: Supports custom ports for HTTPS
-
-## File Structure
-
-```
-keycloak-api-manager/
-├── docker-compose.yml              # HTTP configuration
-├── docker-compose-https.yml         # HTTPS configuration
-├── .env                             # Generated by setup script (gitignored)
-├── .env.example                     # Reference configuration
-└── test/
-    └── setup-keycloak.js            # Interactive setup script
-```
-
-## Certificate Configuration
-
-### Default Location
-For local HTTPS deployments, the script automatically searches for certificates in:
-```
-test/docker-keycloak/certs/
-├── keycloak.crt  (X.509 certificate)
-└── keycloak.key  (Private key)
-```
-
-**If found**: Script uses them automatically ✅  
-**If not found**: Script prompts you to enter a custom path
-
-The default location allows you to:
-- Generate certificates once and commit them to the repo
-- Run the script without entering certificate path every time
-- Keep certificates organized with the deployment infrastructure
-
-### For Remote Deployments - Automatic Certificate Handling
-
-When deploying to a remote server with HTTPS, the script **automatically**:
-1. Loads certificates from the local `test/docker-keycloak/certs/` directory
-2. Verifies they exist (fails with clear error if missing)
-3. Copies them to the remote server in `deployment_path/certs/`
-4. Uses them for the HTTPS configuration
-
-**No manual prompts** - just ensure you have valid certificates in `test/docker-keycloak/certs/`:
-```bash
-test/docker-keycloak/certs/
-├── keycloak.crt
-└── keycloak.key
-```
-
-### For Local Deployments - Custom Certificate Path
-
-For local HTTPS deployments, certificates are first sought in `test/docker-keycloak/certs/`.  
-If not found there, you will be prompted to enter a custom path:
-```bash
-Certificate directory path (or press Enter for default): /path/to/your/certs
-```
-
-### Certificate Files Required
-For HTTPS deployments, ensure the certificate directory contains:
-- `keycloak.crt` - X.509 certificate file
-- `keycloak.key` - Unencrypted private key file
-
-Example self-signed certificate generation:
-```bash
-# Generate self-signed certificate for testing
-openssl req -x509 -newkey rsa:2048 -keyout keycloak.key \
-  -out keycloak.crt -days 365 -nodes \
-  -subj "/CN=keycloak.test/O=Test/C=US"
-
-# Place in the default location
-mkdir -p test/docker-keycloak/certs
-cp keycloak.crt keycloak.key test/docker-keycloak/certs/
-```
-
-## Configuration Details
-
-### Environment Variables
-
-**HTTP Version**:
-- `KEYCLOAK_HOSTNAME`: Hostname for Keycloak (localhost for local, hostname for remote)
-
-**HTTPS Version**:
-- `KEYCLOAK_CERT_PATH`: Path to certificate directory
-- `KEYCLOAK_HOSTNAME`: Hostname for Keycloak (must match certificate CN for production)
-
-### Docker Compose Files
-
-**docker-compose.yml** (HTTP):
-```yaml
-- Image: keycloak/keycloak:latest
-- Ports: 8080 (HTTP)
-- Database: In-memory (KC_DB: dev-mem)
-- Admin Creds: admin:admin
-```
-
-**docker-compose-https.yml** (HTTPS):
-```yaml
-- Image: keycloak/keycloak:latest
-- Ports: 8080 (HTTP), 8443 (HTTPS)
-- Certificates: Mounted from KEYCLOAK_CERT_PATH
-- Admin Creds: admin:admin
-```
-
-## Troubleshooting
-
-### SSH Connection Failed
-```bash
-# Verify SSH access
-ssh -v smart@smart-dell-sml.crs4.it 'echo OK'
-
-# Check SSH key permissions
-ls -la ~/.ssh/id_ed25519
-chmod 600 ~/.ssh/id_ed25519
-```
-
-### HTTPS Certificate Issues
-```bash
-# Verify certificate files exist
-ls -la /path/to/certs/keycloak.crt
-ls -la /path/to/certs/keycloak.key
-
-# Test certificate validity
-openssl x509 -in keycloak.crt -text -noout
-
-# For browser access with self-signed cert:
-# - Use curl -k (insecure flag)
-# - Add browser exception for the domain
-```
-
-### Keycloak Takes Too Long to Start
-```bash
-# Check container logs
-docker-compose -f docker-compose.yml logs -f
-
-# Or remotely
-ssh smart@smart-dell-sml.crs4.it 'cd /home/smart/keycloak && docker-compose -f docker-compose-https.yml logs -f'
-```
-
-### Port Already in Use
-```bash
-# Check what's using the port
-lsof -i :8080
-lsof -i :8443
-
-# Kill existing container
-docker-compose down
-```
-
-## Running Tests with Different Deployments
-
-After deploying Keycloak with the setup script, run tests:
-
-```bash
-# Tests will automatically detect and connect to Keycloak
-npm test
-
-# The test setup handles:
-# - Local HTTP: Connects to http://localhost:8080
-# - Local HTTPS: Connects to https://localhost:8443
-# - Remote: Can be configured in test/config/default.json
-```
-
-## Advanced Configuration
-
-### Custom Keycloak Version
-Edit `docker-compose.yml` or `docker-compose-https.yml`:
-```yaml
-services:
-  keycloak:
-    image: keycloak/keycloak:25.0  # Change version here
-```
-
-### Custom Database
-Edit docker-compose files, change `KC_DB`:
-```yaml
-environment:
-  KC_DB: postgres  # Instead of dev-mem
-  KC_DB_URL_HOST: postgres-host
-  KC_DB_URL_PORT: 5432
-  KC_DB_USERNAME: keycloak
-  KC_DB_PASSWORD: password
-```
-
-### Additional Environment Variables
-Add to `.env`:
-```bash
-KC_LOG_LEVEL=INFO
-KC_METRICS_ENABLED=true
-KC_CACHE=ispn
-```
-
-## Support
-
-For issues or questions:
-- Check Docker logs: `docker-compose logs -f`
-- Check Keycloak admin console: http://localhost:8080
-- Review certificates: `openssl x509 -in keycloak.crt -text -noout`
-- Test connectivity: `curl -k https://localhost:8443/health/ready`

package/test/helpers/setup.js

@@ -1,186 +0,0 @@
-/**
- * Mocha Root Setup Hook
- * Orchestrates Docker container lifecycle and Keycloak initialization
- */
-
-const { startDocker, stopDocker, waitForHealthy, updateConfigFromDocker, createSSHTunnel, closeSSHTunnel } = require('./docker-helpers');
-const { initializeAdminClient, setupTestRealm, cleanupTestRealm, resetConfig } = require('./config');
-
-// Store tunnel state for cleanup
-let sshTunnelUrl = null;
-
-/**
- * Attempt to connect to Keycloak, with automatic SSH tunnel retry
- */
-async function connectWithRetry() {
-  try {
-    console.log('Attempting Keycloak connection...');
-    await initializeAdminClient();
-    console.log('✓ Connected successfully to Keycloak\n');
-  } catch (err) {
-    // Check if connection was refused (tunnel might be needed)
-    if (err.message && err.message.includes('ECONNREFUSED') && err.message.includes('127.0.0.1:9998')) {
-      console.log('⚠ Direct connection failed (ECONNREFUSED on 127.0.0.1:9998)');
-      console.log('  Attempting to create SSH tunnel to smart-dell-sml.crs4.it...\n');
-      
-      try {
-        // Create SSH tunnel
-        sshTunnelUrl = await createSSHTunnel();
-        
-        if (sshTunnelUrl) {
-          console.log(`✓ SSH tunnel created: http://${sshTunnelUrl}`);
-          
-          // Update config to use tunnel
-          const fs = require('fs');
-          const path = require('path');
-          const configPath = path.join(__dirname, '../config/local.json');
-          
-          // Create or update local.json
-          let config = {};
-          if (fs.existsSync(configPath)) {
-            config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-          }
-          
-          if (!config.test) config.test = {};
-          if (!config.test.keycloak) config.test.keycloak = {};
-          config.test.keycloak.baseUrl = `http://${sshTunnelUrl}`;
-          
-          fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
-          console.log(`✓ Updated config to use SSH tunnel\n`);
-          
-          // Reset config cache and retry connection
-          resetConfig();
-          await initializeAdminClient();
-          console.log('✓ Connected successfully via SSH tunnel\n');
-        } else {
-          throw new Error('SSH tunnel creation failed - returned null');
-        }
-      } catch (tunnelErr) {
-        console.error('✗ SSH tunnel connection failed:');
-        console.error(`  Error: ${tunnelErr.message}`);
-        console.error('\nTroubleshooting:');
-        console.error('  1. Verify SSH key: ~/.ssh/id_ed25519 exists');
-        console.error('  2. Verify remote host: smart-dell-sml.crs4.it is reachable');
-        console.error('  3. Verify remote Keycloak: running on smart@smart-dell-sml.crs4.it');
-        console.error('  4. Manual tunnel alternative: ssh -L 127.0.0.1:9998:127.0.0.1:8080 smart@smart-dell-sml.crs4.it');
-        throw new Error(`Failed to connect to Keycloak. Direct connection (127.0.0.1:9998) failed and SSH tunnel creation also failed: ${tunnelErr.message}`);
-      }
-    } else {
-      // Not a connection refused error - propagate as-is
-      throw err;
-    }
-  }
-}
-
-// Root hook plugin for Mocha
-exports.mochaHooks = {
-  async beforeAll() {
-    this.timeout(120000); // 2 minutes max for setup
-
-    console.log('\n========== TEST SETUP ==========');
-
-    if (process.env.SKIP_TEST_SETUP === 'true') {
-      console.log('Skipping global test setup (SKIP_TEST_SETUP=true)\n');
-      return;
-    }
-
-    // Check if using remote Keycloak (skip Docker)
-    const useRemoteKeycloak = process.env.USE_REMOTE_KEYCLOAK === 'true';
-    const useRemoteDocker = !!process.env.DOCKER_SSH_HOST;
-
-    try {
-      if (useRemoteKeycloak) {
-        console.log('Using remote Keycloak (skip Docker startup)');
-        console.log('Configuration from test/config/*.json files\n');
-      } else if (useRemoteDocker) {
-        console.log(`Starting Docker containers on remote host ${process.env.DOCKER_SSH_HOST}...`);
-        
-        // Start Docker Compose on remote host
-        await startDocker();
-
-        // Wait for services to be healthy on remote host
-        await waitForHealthy();
-
-        // Update configuration from remote Docker container
-        await updateConfigFromDocker();
-
-        // Create SSH tunnel for local HTTP access (avoids HTTPS enforcement)
-        sshTunnelUrl = await createSSHTunnel();
-        
-        // Update config to use tunnel
-        if (sshTunnelUrl) {
-          const fs = require('fs');
-          const path = require('path');
-          const configPath = path.join(__dirname, '../config/local.json');
-          const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-          config.test.keycloak.baseUrl = `http://${sshTunnelUrl}`;
-          fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
-          console.log(`✓ Updated config to use SSH tunnel: http://${sshTunnelUrl}`);
-        }
-        
-        // Reset config cache so it reloads from updated local.json
-        resetConfig();
-      } else {
-        console.log('Starting Docker containers locally...');
-        
-        // Start Docker Compose locally
-        await startDocker();
-
-        // Wait for services to be healthy locally
-        await waitForHealthy();
-
-        // Update configuration from local Docker container
-        await updateConfigFromDocker();
-      }
-
-      // Connect to Keycloak (with automatic SSH tunnel retry if needed)
-      await connectWithRetry();
-
-      // Setup test realm
-      await setupTestRealm();
-
-      console.log('✓ Test environment ready\n');
-    } catch (err) {
-      console.error('✗ Test setup failed:', err.message);
-      throw err;
-    }
-  },
-
-  async afterAll() {
-    this.timeout(60000); // 1 minute max for teardown
-
-    console.log('\n========== TEST TEARDOWN ==========');
-
-    if (process.env.SKIP_TEST_SETUP === 'true') {
-      console.log('Skipping global test teardown (SKIP_TEST_SETUP=true)\n');
-      return;
-    }
-
-    const useRemoteKeycloak = process.env.USE_REMOTE_KEYCLOAK === 'true';
-    const useRemoteDocker = !!process.env.DOCKER_SSH_HOST;
-
-    try {
-      // Cleanup Keycloak test realm
-      await cleanupTestRealm();
-
-      // Close SSH tunnel if open
-      if (sshTunnelUrl) {
-        closeSSHTunnel();
-        sshTunnelUrl = null;
-      }
-
-      // Stop Docker Compose only if using local or remote Docker (not pre-deployed)
-      if (!useRemoteKeycloak && !useRemoteDocker) {
-        await stopDocker();
-      } else if (useRemoteDocker) {
-        // Stop Docker on remote host
-        await stopDocker();
-      }
-
-      console.log('✓ Test environment cleaned up\n');
-    } catch (err) {
-      console.error('✗ Test teardown failed:', err.message);
-      // Don't throw during cleanup to allow partial cleanup
-    }
-  },
-};