container-superposition 0.1.3 → 0.1.5

package/overlays/keycloak/README.md

@@ -0,0 +1,238 @@
+# Keycloak Overlay
+
+Open-source identity and access management for developing apps with OAuth2/OIDC authentication.
+
+## Features
+
+- **Keycloak 26** - Latest stable version with OIDC/OAuth2 support
+- **Admin console** - Web UI for managing realms, clients, and users (port 8180)
+- **OIDC/OAuth2** - Full OpenID Connect and OAuth 2.0 support
+- **PostgreSQL backend** - Uses the PostgreSQL overlay as database
+- **Docker Compose service** - Runs as separate container
+- **Development mode** - Pre-configured for local development (no TLS required)
+
+## How It Works
+
+This overlay adds Keycloak as a Docker Compose service alongside your development container. It requires the `postgres` overlay to provide the database backend.
+
+**Architecture:**
+
+```
+Development Container
+  └─ Your application code
+  └─ Connects to keycloak:8180 for auth
+
+Keycloak Container (port 8180)
+  └─ Admin console
+  └─ OIDC/OAuth2 endpoints
+  └─ Connects to postgres:5432
+
+PostgreSQL Container (port 5432)
+  └─ Keycloak database storage
+```
+
+The Keycloak service is accessible from the dev container using the hostname `keycloak`.
+
+## Configuration
+
+### Environment Variables
+
+The overlay includes a `.env.example` file. Copy it to `.env` and customize:
+
+```bash
+cd .devcontainer
+cp .env.example .env
+```
+
+**Default values (.env.example):**
+
+```bash
+# Keycloak Configuration
+KEYCLOAK_VERSION=26.0
+KEYCLOAK_PORT=8180
+KEYCLOAK_ADMIN=admin
+KEYCLOAK_ADMIN_PASSWORD=admin
+```
+
+⚠️ **Security Note:** Default credentials (`admin`/`admin`) are for development only. Never use these in production.
+
+### PostgreSQL Integration
+
+Keycloak uses the PostgreSQL overlay's environment variables:
+
+```bash
+POSTGRES_DB=devdb       # Database name
+POSTGRES_USER=postgres  # Database user
+POSTGRES_PASSWORD=postgres  # Database password
+```
+
+These are configured in the `postgres` overlay's `.env.example`.
+
+## Common Commands
+
+### Access Admin Console
+
+```bash
+# Open in browser
+open http://localhost:8180
+
+# Admin credentials
+# Username: admin (or KEYCLOAK_ADMIN value)
+# Password: admin (or KEYCLOAK_ADMIN_PASSWORD value)
+```
+
+### Realm Management
+
+```bash
+# List realms via Admin REST API
+curl -s \
+  -u admin:admin \
+  http://localhost:8180/admin/realms | jq '.[].realm'
+
+# Create a new realm
+curl -s -X POST \
+  -H "Content-Type: application/json" \
+  -u admin:admin \
+  http://localhost:8180/admin/realms \
+  -d '{"realm": "myrealm", "enabled": true}'
+```
+
+### OIDC Discovery
+
+```bash
+# Discover OIDC endpoints for the master realm
+curl -s http://localhost:8180/realms/master/.well-known/openid-configuration | jq .
+
+# Get discovery for a custom realm
+curl -s http://localhost:8180/realms/myrealm/.well-known/openid-configuration | jq .
+```
+
+### Client Credentials Flow
+
+```bash
+# Get access token using client credentials
+curl -s -X POST \
+  http://localhost:8180/realms/master/protocol/openid-connect/token \
+  -d "client_id=admin-cli" \
+  -d "username=admin" \
+  -d "password=admin" \
+  -d "grant_type=password" | jq .access_token
+```
+
+### Token Introspection
+
+```bash
+TOKEN=$(curl -s -X POST \
+  http://localhost:8180/realms/master/protocol/openid-connect/token \
+  -d "client_id=admin-cli" \
+  -d "username=admin" \
+  -d "password=admin" \
+  -d "grant_type=password" | jq -r .access_token)
+
+# Decode token (base64)
+echo "$TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | jq .
+```
+
+## Application Integration
+
+### Node.js (using openid-client)
+
+```javascript
+import { Issuer } from 'openid-client';
+
+const keycloakIssuer = await Issuer.discover('http://keycloak:8180/realms/myrealm');
+
+const client = new keycloakIssuer.Client({
+    client_id: 'my-app',
+    client_secret: 'my-secret',
+    redirect_uris: ['http://localhost:3000/callback'],
+    response_types: ['code'],
+});
+```
+
+### Python (using requests-oauthlib)
+
+```python
+from requests_oauthlib import OAuth2Session
+
+oauth = OAuth2Session(
+    client_id="my-app",
+    redirect_uri="http://localhost:5000/callback",
+    scope=["openid", "profile", "email"]
+)
+
+authorization_url, state = oauth.authorization_url(
+    "http://keycloak:8180/realms/myrealm/protocol/openid-connect/auth"
+)
+```
+
+### .NET (using Microsoft.AspNetCore.Authentication.OpenIdConnect)
+
+```csharp
+builder.Services.AddAuthentication(options => {
+    options.DefaultScheme = "Cookies";
+    options.DefaultChallengeScheme = "oidc";
+})
+.AddCookie("Cookies")
+.AddOpenIdConnect("oidc", options => {
+    options.Authority = "http://keycloak:8180/realms/myrealm";
+    options.ClientId = "my-app";
+    options.ClientSecret = "my-secret";
+    options.ResponseType = "code";
+    options.RequireHttpsMetadata = false; // Development only
+});
+```
+
+## Use Cases
+
+- **OAuth2/OIDC integration testing** - Test authentication flows end-to-end
+- **Multi-tenant applications** - Create separate realms per tenant
+- **SSO development** - Single Sign-On across multiple local services
+- **Identity federation** - Test social login, LDAP, SAML integration
+- **Role-based access control** - Define and test permissions locally
+
+## Troubleshooting
+
+### Keycloak takes too long to start
+
+Keycloak can take 60–90 seconds on first startup (database schema creation). Wait for the health check to pass:
+
+```bash
+docker-compose logs -f keycloak
+# Look for: "Keycloak X.X started"
+```
+
+### Database connection errors
+
+Ensure PostgreSQL is running and healthy before Keycloak starts:
+
+```bash
+docker-compose ps postgres
+# Should show "healthy"
+```
+
+### Cannot connect from application
+
+Use `keycloak` (not `localhost`) as the hostname when connecting from inside the container:
+
+```bash
+# Correct (from inside dev container)
+http://keycloak:8180/realms/master
+
+# Correct (from host machine browser)
+http://localhost:8180/realms/master
+```
+
+## References
+
+- [Keycloak Documentation](https://www.keycloak.org/documentation)
+- [Keycloak Admin REST API](https://www.keycloak.org/docs-api/latest/rest-api/)
+- [OpenID Connect Specification](https://openid.net/connect/)
+- [Keycloak Docker Image](https://quay.io/repository/keycloak/keycloak)
+
+**Related Overlays:**
+
+- `postgres` - Required database backend
+- `nodejs` - Node.js application development
+- `python` - Python application development
+- `dotnet` - .NET application development

package/overlays/keycloak/devcontainer.patch.json

@@ -0,0 +1,17 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "runServices": ["keycloak"],
+    "_serviceOrder": 10,
+    "forwardPorts": [8180],
+    "portsAttributes": {
+        "8180": {
+            "label": "Keycloak Admin Console",
+            "onAutoForward": "openBrowser"
+        }
+    },
+    "remoteEnv": {
+        "KEYCLOAK_HOST": "keycloak",
+        "KEYCLOAK_PORT": "8180",
+        "KEYCLOAK_ISSUER": "http://keycloak:8180/realms/master"
+    }
+}

package/overlays/keycloak/docker-compose.yml

@@ -0,0 +1,32 @@
+version: '3.8'
+
+services:
+    keycloak:
+        image: quay.io/keycloak/keycloak:${KEYCLOAK_VERSION:-26.0}
+        command: start-dev
+        restart: unless-stopped
+        environment:
+            KC_DB: postgres
+            KC_DB_URL: jdbc:postgresql://postgres:5432/${POSTGRES_DB:-devdb}
+            KC_DB_USERNAME: ${POSTGRES_USER:-postgres}
+            KC_DB_PASSWORD: ${POSTGRES_PASSWORD:-postgres}
+            KEYCLOAK_ADMIN: ${KEYCLOAK_ADMIN:-admin}
+            KEYCLOAK_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD:-admin}
+            KC_HTTP_PORT: 8180
+            KC_HOSTNAME_STRICT: 'false'
+            KC_HTTP_ENABLED: 'true'
+        ports:
+            - '${KEYCLOAK_PORT:-8180}:8180'
+        depends_on:
+            - postgres
+        networks:
+            - devnet
+        healthcheck:
+            test: ['CMD-SHELL', 'curl -sf http://localhost:8180/health/ready || exit 1']
+            interval: 15s
+            timeout: 10s
+            retries: 10
+            start_period: 60s
+
+networks:
+    devnet:

package/overlays/keycloak/overlay.yml

@@ -0,0 +1,23 @@
+id: keycloak
+name: Keycloak
+description: Open-source identity and access management (OIDC/OAuth2)
+category: dev
+supports:
+    - compose
+requires:
+    - postgres
+suggests: []
+conflicts: []
+tags:
+    - dev
+    - auth
+    - oidc
+    - oauth2
+    - identity
+ports:
+    - port: 8180
+      service: keycloak
+      protocol: http
+      description: Keycloak admin console and auth endpoints
+      path: /
+      onAutoForward: openBrowser

package/overlays/keycloak/verify.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# Verification script for Keycloak overlay
+# Confirms Keycloak is running and accessible
+
+set -e
+
+echo "🔍 Verifying Keycloak overlay..."
+echo ""
+
+# Check if curl is available
+echo "1️⃣ Checking curl availability..."
+if ! command -v curl &> /dev/null; then
+    echo "   ❌ curl not found"
+    exit 1
+fi
+echo "   ✅ curl found"
+
+# Check Keycloak health endpoint
+echo ""
+echo "2️⃣ Checking Keycloak service..."
+KEYCLOAK_HOST="${KEYCLOAK_HOST:-keycloak}"
+KEYCLOAK_PORT="${KEYCLOAK_PORT:-8180}"
+KEYCLOAK_READY=false
+
+for i in {1..40}; do
+    if curl -sf "http://${KEYCLOAK_HOST}:${KEYCLOAK_PORT}/health/ready" &> /dev/null; then
+        echo "   ✅ Keycloak service is ready"
+        KEYCLOAK_READY=true
+        break
+    fi
+    sleep 3
+done
+
+if [ "$KEYCLOAK_READY" = false ]; then
+    echo "   ❌ Keycloak service not ready after 2 minutes"
+    echo "   ℹ️  Keycloak can take a while to start on first run"
+    exit 1
+fi
+
+# Check OIDC discovery endpoint
+echo ""
+echo "3️⃣ Checking OIDC discovery endpoint..."
+if curl -sf "http://${KEYCLOAK_HOST}:${KEYCLOAK_PORT}/realms/master/.well-known/openid-configuration" &> /dev/null; then
+    echo "   ✅ OIDC discovery endpoint is accessible"
+else
+    echo "   ❌ OIDC discovery endpoint not accessible"
+    exit 1
+fi
+
+echo ""
+echo "✅ Keycloak overlay verification complete"
+echo "   Admin console: http://localhost:${KEYCLOAK_PORT}"
+echo "   Admin credentials: admin / admin (default)"
+echo "   OIDC discovery: http://localhost:${KEYCLOAK_PORT}/realms/master/.well-known/openid-configuration"

package/overlays/mailpit/.env.example

@@ -0,0 +1,4 @@
+# Mailpit Configuration
+MAILPIT_VERSION=latest
+MAILPIT_UI_PORT=8025
+MAILPIT_SMTP_PORT=1025

package/overlays/mailpit/README.md

@@ -0,0 +1,191 @@
+# Mailpit Overlay
+
+Email testing tool that captures all outbound emails, with a web UI for browsing and an API for automated testing.
+
+## Features
+
+- **Mailpit** - Fast, lightweight email testing tool
+- **Web UI** - Beautiful interface for viewing captured emails (port 8025)
+- **SMTP server** - Accepts all email without authentication (port 1025)
+- **REST API** - Programmatic access to captured messages
+- **Search and filter** - Find emails by recipient, subject, or content
+- **No accidental sends** - All emails are captured locally, never delivered
+
+## How It Works
+
+This overlay adds Mailpit as a Docker Compose service. Configure your application to send emails via SMTP to `mailpit:1025` (from inside the container) and all emails will be captured and visible in the web UI.
+
+## Configuration
+
+### Environment Variables
+
+The overlay includes a `.env.example` file. Copy it to `.env` and customize:
+
+```bash
+cd .devcontainer
+cp .env.example .env
+```
+
+**Default values (.env.example):**
+
+```bash
+# Mailpit Configuration
+MAILPIT_VERSION=latest
+MAILPIT_UI_PORT=8025
+MAILPIT_SMTP_PORT=1025
+```
+
+### SMTP Settings for Your Application
+
+Configure your application to use these settings:
+
+| Setting        | Value                                                  |
+| -------------- | ------------------------------------------------------ |
+| SMTP host      | `mailpit` (inside container) / `localhost` (from host) |
+| SMTP port      | `1025`                                                 |
+| Authentication | None required                                          |
+| TLS/SSL        | Not required                                           |
+
+## Common Commands
+
+### View Captured Emails
+
+```bash
+# Open web UI in browser
+open http://localhost:8025
+
+# List messages via API
+curl -s http://localhost:8025/api/v1/messages | jq .
+
+# Get message count
+curl -s http://localhost:8025/api/v1/info | jq .Messages
+```
+
+### Search Emails
+
+```bash
+# Search by query
+curl -s "http://localhost:8025/api/v1/messages?query=password+reset" | jq .
+
+# Filter by recipient
+curl -s "http://localhost:8025/api/v1/messages?query=to:user@example.com" | jq .
+```
+
+### Clear All Emails
+
+```bash
+# Delete all messages via API
+curl -s -X DELETE http://localhost:8025/api/v1/messages
+```
+
+## Application Configuration Examples
+
+### Node.js (using nodemailer)
+
+```javascript
+import nodemailer from 'nodemailer';
+
+const transporter = nodemailer.createTransport({
+    host: process.env.SMTP_HOST || 'mailpit',
+    port: parseInt(process.env.SMTP_PORT || '1025'),
+    secure: false,
+    auth: null, // No authentication needed
+});
+
+await transporter.sendMail({
+    from: 'noreply@example.com',
+    to: 'user@example.com',
+    subject: 'Welcome!',
+    text: 'Welcome to our app.',
+    html: '<b>Welcome to our app.</b>',
+});
+```
+
+### Python (using smtplib)
+
+```python
+import smtplib
+from email.mime.text import MIMEText
+import os
+
+def send_email(to, subject, body):
+    msg = MIMEText(body, 'html')
+    msg['Subject'] = subject
+    msg['From'] = 'noreply@example.com'
+    msg['To'] = to
+
+    smtp_host = os.getenv('SMTP_HOST', 'mailpit')
+    smtp_port = int(os.getenv('SMTP_PORT', '1025'))
+
+    with smtplib.SMTP(smtp_host, smtp_port) as server:
+        server.sendmail(msg['From'], [to], msg.as_string())
+```
+
+### .NET (using MailKit)
+
+```csharp
+using MailKit.Net.Smtp;
+using MimeKit;
+
+var message = new MimeMessage();
+message.From.Add(new MailboxAddress("App", "noreply@example.com"));
+message.To.Add(new MailboxAddress("User", "user@example.com"));
+message.Subject = "Welcome!";
+message.Body = new TextPart("html") { Text = "<b>Welcome!</b>" };
+
+using var client = new SmtpClient();
+await client.ConnectAsync(
+    Environment.GetEnvironmentVariable("SMTP_HOST") ?? "mailpit",
+    int.Parse(Environment.GetEnvironmentVariable("SMTP_PORT") ?? "1025"),
+    false
+);
+await client.SendAsync(message);
+await client.DisconnectAsync(true);
+```
+
+## Automated Testing
+
+### Check Email was Sent
+
+```bash
+# Send test email, then verify it was received
+curl -s http://localhost:8025/api/v1/messages | jq '.messages | length'
+# Should be > 0
+
+# Get latest email subject
+curl -s http://localhost:8025/api/v1/messages | jq '.messages[0].Subject'
+```
+
+### Integration Test Pattern
+
+```javascript
+// After triggering an action that sends email:
+const response = await fetch('http://localhost:8025/api/v1/messages');
+const data = await response.json();
+
+const latestEmail = data.messages[0];
+expect(latestEmail.To[0].Address).toBe('user@example.com');
+expect(latestEmail.Subject).toBe('Password Reset');
+
+// Clean up for next test
+await fetch('http://localhost:8025/api/v1/messages', { method: 'DELETE' });
+```
+
+## Use Cases
+
+- **Email flow testing** - Verify registration, password reset, and notification emails
+- **Template development** - Preview rendered HTML email templates
+- **Integration testing** - Assert emails are sent with correct content
+- **No accidental sends** - Safely test in development without real email delivery
+
+## References
+
+- [Mailpit Documentation](https://mailpit.axllent.org/docs/)
+- [Mailpit API Reference](https://mailpit.axllent.org/docs/api-v1/)
+- [Mailpit GitHub](https://github.com/axllent/mailpit)
+
+**Related Overlays:**
+
+- `nodejs` - Node.js with nodemailer
+- `python` - Python email development
+- `dotnet` - .NET with MailKit

package/overlays/mailpit/devcontainer.patch.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "runServices": ["mailpit"],
+    "forwardPorts": [8025, 1025],
+    "portsAttributes": {
+        "8025": {
+            "label": "Mailpit Web UI",
+            "onAutoForward": "openBrowser"
+        },
+        "1025": {
+            "label": "Mailpit SMTP",
+            "onAutoForward": "ignore"
+        }
+    },
+    "remoteEnv": {
+        "SMTP_HOST": "mailpit",
+        "SMTP_PORT": "1025",
+        "MAILPIT_URL": "http://mailpit:8025"
+    }
+}

package/overlays/mailpit/docker-compose.yml

@@ -0,0 +1,17 @@
+version: '3.8'
+
+services:
+    mailpit:
+        image: axllent/mailpit:${MAILPIT_VERSION:-latest}
+        restart: unless-stopped
+        environment:
+            MP_SMTP_AUTH_ACCEPT_ANY: '1'
+            MP_SMTP_AUTH_ALLOW_INSECURE: '1'
+        ports:
+            - '${MAILPIT_UI_PORT:-8025}:8025'
+            - '${MAILPIT_SMTP_PORT:-1025}:1025'
+        networks:
+            - devnet
+
+networks:
+    devnet:

package/overlays/mailpit/overlay.yml

@@ -0,0 +1,26 @@
+id: mailpit
+name: Mailpit
+description: Email testing tool with web UI and SMTP server
+category: dev
+supports:
+    - compose
+requires: []
+suggests: []
+conflicts: []
+tags:
+    - dev
+    - email
+    - smtp
+    - testing
+ports:
+    - port: 8025
+      service: mailpit
+      protocol: http
+      description: Mailpit web UI
+      path: /
+      onAutoForward: openBrowser
+    - port: 1025
+      service: mailpit
+      protocol: tcp
+      description: Mailpit SMTP server
+      onAutoForward: ignore

package/overlays/mailpit/verify.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# Verification script for Mailpit overlay
+# Confirms Mailpit is running and accessible
+
+set -e
+
+echo "🔍 Verifying Mailpit overlay..."
+echo ""
+
+# Check if curl is available
+echo "1️⃣ Checking curl availability..."
+if ! command -v curl &> /dev/null; then
+    echo "   ❌ curl not found"
+    exit 1
+fi
+echo "   ✅ curl found"
+
+# Check Mailpit web UI
+echo ""
+echo "2️⃣ Checking Mailpit service..."
+MAILPIT_HOST="${MAILPIT_HOST:-mailpit}"
+MAILPIT_UI_PORT="${MAILPIT_UI_PORT:-8025}"
+MAILPIT_READY=false
+
+for i in {1..20}; do
+    if curl -sf "http://${MAILPIT_HOST}:${MAILPIT_UI_PORT}/api/v1/info" &> /dev/null; then
+        echo "   ✅ Mailpit service is ready"
+        MAILPIT_READY=true
+        break
+    fi
+    sleep 2
+done
+
+if [ "$MAILPIT_READY" = false ]; then
+    echo "   ❌ Mailpit service not ready after 40 seconds"
+    exit 1
+fi
+
+# Check Mailpit API
+echo ""
+echo "3️⃣ Checking Mailpit API..."
+if curl -sf "http://${MAILPIT_HOST}:${MAILPIT_UI_PORT}/api/v1/messages" &> /dev/null; then
+    echo "   ✅ Mailpit API is accessible"
+else
+    echo "   ❌ Mailpit API not accessible"
+    exit 1
+fi
+
+echo ""
+echo "✅ Mailpit overlay verification complete"
+echo "   Web UI: http://localhost:${MAILPIT_UI_PORT}"
+echo "   SMTP server: mailpit:1025 (from inside container)"

package/overlays/ngrok/overlay.yml

@@ -5,7 +5,8 @@ category: dev
 supports: []
 requires: []
 suggests: []
-conflicts: []
+conflicts:
+    - cloudflared
 tags:
     - dev
     - tunneling