container-superposition 0.1.1 → 0.1.4

package/overlays/localstack/.env.example

@@ -0,0 +1,6 @@
+# LocalStack Configuration
+LOCALSTACK_VERSION=latest
+LOCALSTACK_SERVICES=s3,sqs,sns,dynamodb,lambda,cloudformation
+LOCALSTACK_DEBUG=0
+LOCALSTACK_EDGE_PORT=4566
+LOCALSTACK_S3_PORT=4571

package/overlays/localstack/README.md

@@ -0,0 +1,188 @@
+# LocalStack Overlay
+
+Local AWS cloud stack for development and testing without requiring an AWS account.
+
+## Features
+
+- **LocalStack** - Full AWS cloud emulator running locally
+- **Multiple AWS Services** - S3, DynamoDB, SQS, SNS, Lambda, CloudFormation, and more
+- **Docker Compose service** - Runs as separate container
+- **Persistent storage** - Data survives container restarts
+- **Pre-configured environment** - AWS CLI ready to use with LocalStack endpoints
+
+## How It Works
+
+This overlay adds LocalStack as a Docker Compose service that emulates AWS cloud services locally. The service runs in its own container and is accessible from your development container via the hostname `localstack`.
+
+**Architecture:**
+
+- Edge API endpoint: `http://localstack:4566` (all services)
+- S3 endpoint: `http://localstack:4571` (S3-specific)
+- Services run inside LocalStack container
+- Data persisted to Docker volume
+
+## 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
+# LocalStack Configuration
+LOCALSTACK_VERSION=latest
+LOCALSTACK_SERVICES=s3,sqs,sns,dynamodb,lambda,cloudformation
+LOCALSTACK_DEBUG=0
+LOCALSTACK_EDGE_PORT=4566
+LOCALSTACK_S3_PORT=4571
+```
+
+### Available Services
+
+LocalStack supports many AWS services. Common ones include:
+
+- **Storage**: S3, EFS
+- **Databases**: DynamoDB, RDS, Redshift
+- **Messaging**: SQS, SNS, Kinesis
+- **Compute**: Lambda, ECS, Batch
+- **Infrastructure**: CloudFormation, CloudWatch
+
+Set `LOCALSTACK_SERVICES` to enable specific services or use `LOCALSTACK_SERVICES=` (empty) to enable all.
+
+### Port Configuration
+
+The default ports (4566, 4571) can be changed via the `--port-offset` option when initializing the devcontainer:
+
+```bash
+npm run init -- --port-offset 100 --stack compose --cloud localstack
+# LocalStack Edge will be on port 4666, S3 on port 4671
+```
+
+## Common Commands
+
+### AWS CLI Usage
+
+The `aws-cli` overlay integrates seamlessly with LocalStack:
+
+```bash
+# AWS CLI automatically uses LocalStack endpoints via AWS_ENDPOINT_URL
+aws s3 ls
+aws s3 mb s3://my-bucket
+aws s3 cp myfile.txt s3://my-bucket/
+
+# DynamoDB
+aws dynamodb list-tables
+aws dynamodb create-table --table-name MyTable \
+  --attribute-definitions AttributeName=id,AttributeType=S \
+  --key-schema AttributeName=id,KeyType=HASH \
+  --billing-mode PAY_PER_REQUEST
+
+# SQS
+aws sqs list-queues
+aws sqs create-queue --queue-name my-queue
+aws sqs send-message --queue-url http://localstack:4566/000000000000/my-queue \
+  --message-body "Hello LocalStack"
+
+# Lambda
+aws lambda list-functions
+```
+
+### Health Check
+
+```bash
+# Check LocalStack health
+curl http://localstack:4566/_localstack/health
+
+# Check specific service
+curl http://localstack:4566/_localstack/health | jq '.services.s3'
+```
+
+### Direct API Calls
+
+```bash
+# S3 via REST API
+curl http://localstack:4566/my-bucket
+
+# List buckets
+aws --endpoint-url=http://localstack:4566 s3 ls
+```
+
+## Use Cases
+
+- **Cloud development without AWS account** - Develop and test AWS-based applications locally
+- **Integration testing** - Test cloud integrations without external dependencies
+- **Learning AWS services** - Experiment with AWS APIs without cost
+- **CI/CD pipelines** - Run AWS-dependent tests in CI without credentials
+- **Event-driven architectures** - Test SQS, SNS, Lambda workflows locally
+
+**Integrates well with:**
+
+- `aws-cli` - AWS command-line interface (suggested)
+- `terraform` - Infrastructure as Code testing
+- `pulumi` - Infrastructure as Code testing
+- Node.js, Python, .NET - Application development with AWS SDK
+
+## Differences from Real AWS
+
+LocalStack aims for high fidelity but has some differences:
+
+- **Authentication** - Uses test credentials (no real IAM)
+- **Performance** - May be faster or slower than real AWS
+- **Feature parity** - Not all AWS features supported
+- **Behavior** - Some edge cases may differ
+
+For production deployments, always test on real AWS.
+
+## Troubleshooting
+
+### Service Not Ready
+
+If LocalStack takes time to start:
+
+```bash
+# Check logs
+docker-compose logs localstack
+
+# Wait for health check
+curl http://localstack:4566/_localstack/health
+```
+
+### Connection Refused
+
+Ensure the service is running:
+
+```bash
+# Check service status
+docker-compose ps localstack
+
+# Restart if needed
+docker-compose restart localstack
+```
+
+### Services Not Available
+
+Enable specific services in `.env`:
+
+```bash
+LOCALSTACK_SERVICES=s3,dynamodb,sqs,sns,lambda
+```
+
+## References
+
+- [LocalStack Documentation](https://docs.localstack.cloud/)
+- [LocalStack GitHub](https://github.com/localstack/localstack)
+- [Supported AWS Services](https://docs.localstack.cloud/user-guide/aws/feature-coverage/)
+- [AWS CLI with LocalStack](https://docs.localstack.cloud/user-guide/integrations/aws-cli/)
+
+**Related Overlays:**
+
+- `aws-cli` - AWS command-line interface
+- `terraform` - Infrastructure as Code
+- `pulumi` - Infrastructure as Code
+- `nodejs`, `python`, `dotnet` - Application development

package/overlays/localstack/devcontainer.patch.json

@@ -0,0 +1,21 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "runServices": ["localstack"],
+    "forwardPorts": [4566, 4571],
+    "portsAttributes": {
+        "4566": {
+            "label": "LocalStack Edge",
+            "onAutoForward": "notify"
+        },
+        "4571": {
+            "label": "LocalStack S3",
+            "onAutoForward": "ignore"
+        }
+    },
+    "remoteEnv": {
+        "AWS_ENDPOINT_URL": "http://localstack:4566",
+        "AWS_ACCESS_KEY_ID": "test",
+        "AWS_SECRET_ACCESS_KEY": "test",
+        "AWS_DEFAULT_REGION": "us-east-1"
+    }
+}

package/overlays/localstack/docker-compose.yml

@@ -0,0 +1,25 @@
+version: '3.8'
+
+services:
+    localstack:
+        image: localstack/localstack:${LOCALSTACK_VERSION:-latest}
+        restart: unless-stopped
+        volumes:
+            - localstack-data:/var/lib/localstack
+            - /var/run/docker.sock:/var/run/docker.sock
+        environment:
+            SERVICES: ${LOCALSTACK_SERVICES:-s3,sqs,sns,dynamodb,lambda,cloudformation}
+            DEBUG: ${LOCALSTACK_DEBUG:-0}
+            DATA_DIR: /var/lib/localstack
+            DOCKER_HOST: unix:///var/run/docker.sock
+        ports:
+            - '${LOCALSTACK_EDGE_PORT:-4566}:4566'
+            - '${LOCALSTACK_S3_PORT:-4571}:4571'
+        networks:
+            - devnet
+
+volumes:
+    localstack-data:
+
+networks:
+    devnet:

package/overlays/localstack/overlay.yml

@@ -0,0 +1,18 @@
+id: localstack
+name: LocalStack
+description: Local AWS cloud stack for development and testing
+category: cloud
+supports:
+    - compose
+requires: []
+suggests:
+    - aws-cli
+conflicts: []
+tags:
+    - cloud
+    - aws
+    - testing
+    - localstack
+ports:
+    - 4566
+    - 4571

package/overlays/localstack/verify.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+# Verification script for LocalStack overlay
+# Confirms LocalStack is running and accessible
+
+set -e
+
+echo "🔍 Verifying LocalStack overlay..."
+echo ""
+
+# Check if LocalStack service is running
+echo "1️⃣ Checking LocalStack service..."
+if command -v curl &> /dev/null; then
+    # Wait up to 30 seconds for LocalStack to be ready
+    LOCALSTACK_READY=false
+    for i in {1..30}; do
+        if curl -s http://localstack:4566/_localstack/health &> /dev/null; then
+            echo "   ✅ LocalStack service is ready"
+            LOCALSTACK_READY=true
+            break
+        fi
+        sleep 1
+    done
+
+    if [ "$LOCALSTACK_READY" = false ]; then
+        echo "   ❌ LocalStack service not ready after 30 seconds"
+        exit 1
+    fi
+else
+    echo "   ⚠️  curl not found, skipping service check"
+fi
+
+# Check LocalStack health
+echo ""
+echo "2️⃣ Checking LocalStack health..."
+if command -v curl &> /dev/null; then
+    HEALTH=$(curl -s http://localstack:4566/_localstack/health)
+    if [ -n "$HEALTH" ]; then
+        echo "   ✅ LocalStack health endpoint responding"
+        echo "$HEALTH" | head -3
+    else
+        echo "   ❌ LocalStack health check failed"
+        exit 1
+    fi
+fi
+
+echo ""
+echo "✅ LocalStack overlay verification complete"

package/overlays/loki/overlay.yml

@@ -13,5 +13,10 @@ tags:
     - logs
     - loki
 ports:
-    - 3100
+    - port: 3100
+      service: loki
+      protocol: http
+      description: Loki HTTP API and query interface
+      path: /
+      onAutoForward: notify
 order: 1

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/modern-cli-tools/overlay.yml

@@ -11,3 +11,4 @@ tags:
     - cli
     - productivity
 ports: []
+minimal: true

package/overlays/mongodb/overlay.yml

@@ -13,5 +13,15 @@ tags:
     - mongodb
     - document
 ports:
-    - 27017
-    - 8081
+    - port: 27017
+      service: mongodb
+      protocol: tcp
+      description: MongoDB database connection
+      onAutoForward: notify
+      connectionStringTemplate: 'mongodb://{mongo_initdb_root_username}:{mongo_initdb_root_password}@{host}:{port}/'
+    - port: 8081
+      service: mongo-express
+      protocol: http
+      description: Mongo Express web UI
+      path: /
+      onAutoForward: openBrowser

package/overlays/mysql/overlay.yml

@@ -12,5 +12,15 @@ tags:
     - sql
     - mysql
 ports:
-    - 3306
-    - 8080
+    - port: 3306
+      service: mysql
+      protocol: tcp
+      description: MySQL database connection
+      onAutoForward: notify
+      connectionStringTemplate: 'mysql://{mysql_user}:{mysql_password}@{host}:{port}/{mysql_database}'
+    - port: 8080
+      service: phpmyadmin
+      protocol: http
+      description: phpMyAdmin web UI
+      path: /
+      onAutoForward: openBrowser