container-superposition 0.1.1

package/overlays/jaeger/devcontainer.patch.json

@@ -0,0 +1,12 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "runServices": ["jaeger"],
+    "_serviceOrder": 1,
+    "forwardPorts": [16686],
+    "portsAttributes": {
+        "16686": {
+            "label": "Jaeger UI",
+            "onAutoForward": "openBrowser"
+        }
+    }
+}

package/overlays/jaeger/docker-compose.yml

@@ -0,0 +1,17 @@
+version: '3.8'
+services:
+    jaeger:
+        image: jaegertracing/all-in-one:${JAEGER_VERSION:-latest}
+        environment:
+            - COLLECTOR_OTLP_ENABLED=true
+        ports:
+            - '${JAEGER_UI_PORT:-16686}:16686' # Jaeger UI
+            # - "${JAEGER_OTLP_GRPC_PORT:-4317}:4317"   # OTLP gRPC receiver
+            # - "${JAEGER_OTLP_HTTP_PORT:-4318}:4318"   # OTLP HTTP receiver
+            # Note: OTLP ports (4317/4318) are not exposed to avoid conflict with otel-collector
+            # Apps should send telemetry to otel-collector, which forwards to Jaeger if both are used
+        networks:
+            - devnet
+
+networks:
+    devnet:

package/overlays/jaeger/overlay.yml

@@ -0,0 +1,19 @@
+id: jaeger
+name: Jaeger
+description: Distributed tracing backend
+category: observability
+supports:
+    - compose
+requires: []
+suggests: []
+conflicts:
+    - tempo
+tags:
+    - observability
+    - tracing
+    - jaeger
+ports:
+    - 16686
+    - 14250
+    - 14268
+order: 1

package/overlays/java/README.md

@@ -0,0 +1,267 @@
+# Java Overlay
+
+Adds Eclipse Temurin JDK 21 (LTS) with Maven and Gradle for enterprise Java development.
+
+## Features
+
+- **Eclipse Temurin JDK 21** (LTS) - Open-source Java runtime
+- **Maven** - Dependency management and build tool
+- **Gradle** - Modern build automation
+- **VS Code Extensions:**
+    - Java Extension Pack (vscjava.vscode-java-pack) - Complete Java IDE experience
+    - Gradle for Java (vscjava.vscode-gradle)
+    - Maven for Java (vscjava.vscode-maven)
+- **Language Server Protocol** - IntelliSense, refactoring, debugging
+- **Automatic dependency installation** - Runs Maven/Gradle on container creation
+
+## How It Works
+
+This overlay uses the official devcontainers Java feature to install Eclipse Temurin JDK 21 with Maven and Gradle. The Java Extension Pack provides comprehensive IDE features including IntelliSense, debugging, test running, and project management.
+
+**Installation method:**
+
+- Eclipse Temurin JDK via SDKMAN
+- Maven and Gradle installed via devcontainer feature
+- Java tools accessible via PATH
+
+## Common Commands
+
+### Maven Projects
+
+```bash
+# Create new Maven project
+mvn archetype:generate \
+  -DgroupId=com.example \
+  -DartifactId=my-app \
+  -DarchetypeArtifactId=maven-archetype-quickstart \
+  -DinteractiveMode=false
+
+# Build project
+mvn clean install
+
+# Run application
+mvn exec:java -Dexec.mainClass="com.example.App"
+
+# Run tests
+mvn test
+
+# Package JAR
+mvn package
+
+# Skip tests
+mvn install -DskipTests
+```
+
+### Gradle Projects
+
+```bash
+# Initialize new project
+gradle init --type java-application
+
+# Build project
+gradle build
+
+# Run application
+gradle run
+
+# Run tests
+gradle test
+
+# Create JAR
+gradle jar
+
+# Clean build
+gradle clean build
+```
+
+### Spring Boot
+
+```bash
+# Maven - Run Spring Boot app
+mvn spring-boot:run
+
+# Gradle - Run Spring Boot app
+gradle bootRun
+
+# Build executable JAR
+mvn clean package
+# or
+gradle bootJar
+
+# Run with profiles
+mvn spring-boot:run -Dspring-boot.run.profiles=dev
+```
+
+### Dependency Management
+
+```bash
+# Maven - Add dependency (edit pom.xml)
+# Then resolve:
+mvn dependency:resolve
+
+# Display dependency tree
+mvn dependency:tree
+
+# Gradle - Add dependency (edit build.gradle)
+# Then sync:
+gradle dependencies
+
+# Display dependency tree
+gradle dependencies --configuration compileClasspath
+```
+
+## Use Cases
+
+- **Spring Boot applications** - REST APIs, microservices, web applications
+- **Enterprise Java** - J2EE, Jakarta EE applications
+- **Apache Kafka** - Event streaming applications
+- **Android backend** - Services for mobile apps
+- **Data processing** - Apache Spark, Hadoop jobs
+- **Microservices** - Cloud-native Java services
+
+**Integrates well with:**
+
+- `postgres`, `mysql`, `mongodb` - Database connectivity (JDBC)
+- `redis` - Caching layer (Jedis, Lettuce)
+- Apache Kafka - Event streaming (Spring Kafka)
+- `otel-collector`, `jaeger` - Distributed tracing (OpenTelemetry Java)
+- `prometheus`, `grafana` - Metrics and monitoring (Micrometer)
+
+## Configuration
+
+### JDK Version
+
+The overlay installs **Java 21 (LTS)**. To use a different version, modify `devcontainer.patch.json`:
+
+```json
+{
+    "features": {
+        "ghcr.io/devcontainers/features/java:1": {
+            "version": "17" // Change to 17, 21, or latest
+        }
+    }
+}
+```
+
+### Maven Settings
+
+Custom Maven settings can be placed in `~/.m2/settings.xml`:
+
+```xml
+<settings>
+  <mirrors>
+    <mirror>
+      <id>central</id>
+      <url>https://repo.maven.apache.org/maven2</url>
+      <mirrorOf>central</mirrorOf>
+    </mirror>
+  </mirrors>
+</settings>
+```
+
+### Gradle Properties
+
+Custom Gradle properties in `~/.gradle/gradle.properties`:
+
+```properties
+org.gradle.daemon=true
+org.gradle.parallel=true
+org.gradle.caching=true
+```
+
+## Application Integration
+
+### Spring Boot Example
+
+**pom.xml:**
+
+```xml
+<dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-web</artifactId>
+</dependency>
+```
+
+**Application.java:**
+
+```java
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@SpringBootApplication
+@RestController
+public class Application {
+    public static void main(String[] args) {
+        SpringApplication.run(Application.class, args);
+    }
+
+    @GetMapping("/")
+    public String hello() {
+        return "Hello from Spring Boot!";
+    }
+}
+```
+
+**Run:**
+
+```bash
+mvn spring-boot:run
+# Access at http://localhost:8080
+```
+
+## Troubleshooting
+
+### Issue: JAVA_HOME not set
+
+**Solution:**
+
+```bash
+# Check JAVA_HOME
+echo $JAVA_HOME
+
+# Should output: /usr/local/sdkman/candidates/java/current
+
+# If not set, add to shell profile
+export JAVA_HOME=/usr/local/sdkman/candidates/java/current
+```
+
+### Issue: Maven/Gradle not found
+
+**Symptoms:**
+
+- `mvn: command not found`
+- `gradle: command not found`
+
+**Solution:**
+Rebuild the devcontainer - Maven and Gradle are installed via the Java feature.
+
+### Issue: Out of memory during build
+
+**Solution:**
+
+```bash
+# Maven - increase heap size
+export MAVEN_OPTS="-Xmx2048m"
+mvn clean install
+
+# Gradle - configure in gradle.properties
+org.gradle.jvmargs=-Xmx2048m
+```
+
+## References
+
+- [Eclipse Temurin](https://adoptium.net/) - Open-source JDK distribution
+- [Maven Documentation](https://maven.apache.org/guides/) - Build tool
+- [Gradle Documentation](https://docs.gradle.org/) - Build automation
+- [Spring Boot](https://spring.io/projects/spring-boot) - Framework for Java apps
+- [Java Extension Pack](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack)
+
+**Related Overlays:**
+
+- `postgres` - PostgreSQL database (JDBC)
+- `redis` - Redis cache (Jedis, Lettuce)
+- `docker-sock` - Docker access for Testcontainers
+- `prometheus` - Metrics collection (Micrometer)
+- `jaeger` - Distributed tracing (OpenTelemetry)

package/overlays/java/devcontainer.patch.json

@@ -0,0 +1,44 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "build-essential",
+            "apk": "build-base"
+        },
+        "ghcr.io/devcontainers/features/java:1": {
+            "version": "21",
+            "jdkDistro": "tem",
+            "installGradle": "true",
+            "installMaven": "true"
+        }
+    },
+    "customizations": {
+        "vscode": {
+            "extensions": [
+                "vscjava.vscode-java-pack",
+                "vscjava.vscode-gradle",
+                "vscjava.vscode-maven"
+            ],
+            "settings": {
+                "java.configuration.runtimes": [],
+                "[java]": {
+                    "editor.formatOnSave": true
+                }
+            }
+        }
+    },
+    "remoteEnv": {
+        "JAVA_HOME": "/usr/local/sdkman/candidates/java/current"
+    },
+    "forwardPorts": [8080, 8081],
+    "portsAttributes": {
+        "8080": {
+            "label": "Web App",
+            "onAutoForward": "openBrowser"
+        },
+        "8081": {
+            "label": "Admin/Actuator",
+            "onAutoForward": "notify"
+        }
+    }
+}

package/overlays/java/overlay.yml

@@ -0,0 +1,16 @@
+id: java
+name: Java
+description: Eclipse Temurin JDK 21 with Maven and Gradle
+category: language
+supports: []
+requires: []
+suggests: []
+conflicts: []
+tags:
+    - language
+    - java
+    - maven
+    - gradle
+ports:
+    - 8080
+    - 8081

package/overlays/java/setup.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# Java setup script - Verify Java, Maven, and Gradle installation
+
+set -e
+
+echo "🔧 Setting up Java development environment..."
+
+# Verify Java is installed
+if command -v java &> /dev/null; then
+    JAVA_VERSION=$(java -version 2>&1 | head -n 1)
+    echo "✓ Java found: $JAVA_VERSION"
+else
+    echo "⚠️ Java not found"
+fi
+
+# Verify Maven is installed
+if command -v mvn &> /dev/null; then
+    MVN_VERSION=$(mvn -version | head -n 1)
+    echo "✓ Maven found: $MVN_VERSION"
+else
+    echo "⚠️ Maven not found"
+fi
+
+# Verify Gradle is installed
+if command -v gradle &> /dev/null; then
+    GRADLE_VERSION=$(gradle --version | grep "Gradle " | head -n 1)
+    echo "✓ Gradle found: $GRADLE_VERSION"
+else
+    echo "⚠️ Gradle not found"
+fi
+
+# Install Maven/Gradle project dependencies if build files exist
+if [ -f "pom.xml" ]; then
+    echo "📦 Maven project detected, installing dependencies..."
+    mvn dependency:resolve || echo "⚠️ Maven dependency installation failed or skipped"
+elif [ -f "build.gradle" ] || [ -f "build.gradle.kts" ]; then
+    echo "📦 Gradle project detected, installing dependencies..."
+    gradle dependencies || echo "⚠️ Gradle dependency installation failed or skipped"
+fi
+
+echo "✓ Java setup complete"

package/overlays/java/verify.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# Verification script for Java overlay
+
+set -e
+
+echo "🔍 Verifying Java overlay..."
+echo ""
+
+# Check Java is installed
+echo "1️⃣ Checking Java..."
+if command -v java &> /dev/null; then
+    java -version
+    echo "   ✅ Java found"
+else
+    echo "   ❌ Java not found"
+    exit 1
+fi
+
+# Check Maven is installed
+echo ""
+echo "2️⃣ Checking Maven..."
+if command -v mvn &> /dev/null; then
+    mvn --version | head -n 1
+    echo "   ✅ Maven found"
+else
+    echo "   ❌ Maven not found"
+    exit 1
+fi
+
+# Check Gradle is installed
+echo ""
+echo "3️⃣ Checking Gradle..."
+if command -v gradle &> /dev/null; then
+    gradle --version | grep "Gradle " | head -n 1
+    echo "   ✅ Gradle found"
+else
+    echo "   ❌ Gradle not found"
+    exit 1
+fi
+
+echo ""
+echo "✅ Java overlay verification complete"