container-superposition 0.1.1

package/overlays/minio/setup.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+# MinIO setup script - installs MinIO client (mc) and creates default bucket
+
+set -e
+
+echo "🔧 Setting up MinIO client..."
+
+# Install MinIO client (mc)
+echo "📦 Installing MinIO client (mc)..."
+if ! command -v mc &> /dev/null; then
+    # Pin to a specific version for security and reproducibility
+    MC_VERSION="RELEASE.2024-11-17T19-35-25Z"
+    MC_URL="https://dl.min.io/client/mc/release/linux-amd64/archive/mc.${MC_VERSION}"
+    MC_CHECKSUM="27e18faeabd9a0c8066e3b4aadb13a2c0ae4dac09a1e24defe34c99a11b59e26"
+    
+    echo "   Downloading MinIO client version ${MC_VERSION}..."
+    wget -q "${MC_URL}" -O /tmp/mc
+    
+    # Verify checksum
+    echo "   Verifying checksum..."
+    echo "${MC_CHECKSUM}  /tmp/mc" | sha256sum -c - || {
+        echo "   ❌ Checksum verification failed!"
+        rm -f /tmp/mc
+        exit 1
+    }
+    
+    sudo install /tmp/mc /usr/local/bin/
+    rm /tmp/mc
+    echo "   ✅ MinIO client installed (${MC_VERSION})"
+else
+    echo "   ✅ MinIO client already installed"
+fi
+
+# Wait for MinIO to be ready
+echo "⏳ Waiting for MinIO service..."
+for i in {1..30}; do
+    if curl -s http://minio:9000/minio/health/live &> /dev/null; then
+        echo "   ✅ MinIO is ready"
+        break
+    fi
+    sleep 2
+done
+
+# Configure mc alias
+echo "🔗 Configuring MinIO client..."
+mc alias set local http://minio:9000 minioadmin minioadmin || echo "⚠️  MinIO alias setup failed (may already exist)"
+
+# Create default bucket if specified in .env
+if [ -f ".devcontainer/.env" ] && grep -q "MINIO_DEFAULT_BUCKET=" .devcontainer/.env; then
+    BUCKET_NAME=$(grep "MINIO_DEFAULT_BUCKET=" .devcontainer/.env | cut -d'=' -f2)
+    if [ -n "$BUCKET_NAME" ]; then
+        echo "📦 Creating default bucket: $BUCKET_NAME"
+        mc mb local/$BUCKET_NAME --ignore-existing || echo "   ⚠️  Bucket may already exist"
+    fi
+fi
+
+echo "✅ MinIO setup complete"
+echo ""
+echo "📝 MinIO Console: http://localhost:9001"
+echo "   Username: minioadmin"
+echo "   Password: minioadmin"

package/overlays/minio/verify.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+# Verification script for MinIO overlay
+# Confirms MinIO service and client are accessible
+
+set -e
+
+echo "🔍 Verifying MinIO overlay..."
+echo ""
+
+# Check MinIO client is installed
+echo "1️⃣ Checking MinIO client (mc)..."
+if command -v mc &> /dev/null; then
+    mc --version
+    echo "   ✅ MinIO client found"
+else
+    echo "   ❌ MinIO client not found"
+    exit 1
+fi
+
+# Check if MinIO service is running
+echo ""
+echo "2️⃣ Checking MinIO service..."
+MINIO_READY=false
+for i in {1..15}; do
+    if curl -s http://minio:9000/minio/health/live &> /dev/null; then
+        echo "   ✅ MinIO service is ready"
+        MINIO_READY=true
+        break
+    fi
+    sleep 1
+done
+
+if [ "$MINIO_READY" = false ]; then
+    echo "   ❌ MinIO service not ready after 15 seconds"
+    exit 1
+fi
+
+# Check MinIO Console
+echo ""
+echo "3️⃣ Checking MinIO Console..."
+if curl -s -o /dev/null -w "%{http_code}" http://minio:9001 | grep -q "200\|307"; then
+    echo "   ✅ MinIO Console is accessible"
+else
+    echo "   ⚠️  MinIO Console may still be starting up"
+fi
+
+# Test MinIO client connection
+echo ""
+echo "4️⃣ Testing MinIO client connection..."
+if mc alias list | grep -q "local"; then
+    echo "   ✅ MinIO client configured"
+    
+    # Try listing buckets
+    if mc ls local &> /dev/null; then
+        echo "   ✅ Can list buckets"
+    else
+        echo "   ⚠️  Cannot list buckets (may need credentials)"
+    fi
+else
+    echo "   ⚠️  MinIO client alias not configured"
+fi
+
+echo ""
+echo "✅ MinIO overlay verification complete"

package/overlays/mkdocs/README.md

@@ -0,0 +1,309 @@
+# MkDocs Overlay
+
+Material for MkDocs - professional documentation generator.
+
+## Features
+
+- **MkDocs** with Material theme (via official devcontainers-extra feature)
+- **Common MkDocs plugins:**
+    - mkdocs-material
+    - mkdocs-minify-plugin
+    - mkdocs-redirects
+    - pymdown-extensions
+- **Python dependency:** Automatically includes Python overlay (required)
+- **VS Code Extensions:**
+    - Markdown All in One
+    - Markdown Lint
+    - Markdown Mermaid
+- **Port forwarding:** 8000 (MkDocs dev server, auto-opens in browser)
+
+## Dependencies
+
+This overlay requires the **Python** overlay, which is automatically selected through the dependency model.
+
+## Customizing MkDocs Plugins
+
+To add more MkDocs plugins, you can install them via pip in your project's container:
+
+```bash
+# In devcontainer terminal
+pip install mkdocs-git-revision-date-localized-plugin
+pip install mkdocs-awesome-pages-plugin
+pip install mkdocs-macros-plugin
+```
+
+Or add them to your project's `requirements.txt`:
+
+```plaintext
+mkdocs-git-revision-date-localized-plugin>=1.2.0
+mkdocs-awesome-pages-plugin>=2.9.0
+mkdocs-macros-plugin>=1.0.0
+```
+
+**Rebuild container** after editing to install new plugins.
+
+## Quick Start
+
+### New Documentation Site
+
+```bash
+# Create new MkDocs project
+mkdocs new .
+
+# Start development server
+mkdocs serve
+# Opens at http://localhost:8000
+```
+
+### Existing Site
+
+If you already have `mkdocs.yml`:
+
+```bash
+# Start development server
+mkdocs serve
+
+# Build static site
+mkdocs build
+```
+
+## MkDocs Configuration
+
+### Basic mkdocs.yml
+
+```yaml
+site_name: My Documentation
+theme:
+    name: material
+    palette:
+        scheme: default
+        primary: indigo
+        accent: indigo
+    features:
+        - navigation.sections
+        - navigation.expand
+        - toc.integrate
+
+nav:
+    - Home: index.md
+    - About: about.md
+
+markdown_extensions:
+    - pymdownx.highlight
+    - pymdownx.superfences
+    - pymdownx.tabbed
+    - admonition
+```
+
+### Common Plugins
+
+```yaml
+plugins:
+    - search
+    - minify:
+          minify_html: true
+    - redirects:
+          redirect_maps:
+              'old-page.md': 'new-page.md'
+```
+
+## Project Structure
+
+```
+my-docs/
+├── .devcontainer/
+│   └── devcontainer.json
+├── mkdocs.yml          # Configuration
+├── docs/               # Markdown files
+│   ├── index.md
+│   ├── about.md
+│   └── images/
+├── requirements.txt    # Optional: additional dependencies
+└── site/               # Built site (git-ignored)
+```
+
+## Additional Dependencies
+
+If you need extra Python packages for MkDocs plugins, you have two options:
+
+### Option 1: Edit requirements-overlay.txt (Recommended)
+
+Edit `.devcontainer/requirements-overlay.txt`:
+
+```
+mkdocs>=1.5.0
+mkdocs-material>=9.0.0
+mkdocs-git-revision-date-localized-plugin>=1.2.0
+mkdocs-awesome-pages-plugin>=2.9.0
+mkdocs-macros-plugin>=1.0.0
+```
+
+Rebuild the container to install.
+
+### Option 2: Project requirements.txt
+
+Create `requirements.txt` in your project root:
+
+```
+mkdocs-git-revision-date-localized-plugin
+mkdocs-awesome-pages-plugin
+mkdocs-macros-plugin
+```
+
+This is useful if you want to version control plugin dependencies separately.
+
+## Common Workflows
+
+### Documentation as Code
+
+```yaml
+# mkdocs.yml
+plugins:
+    - search
+    - git-revision-date-localized:
+          type: date
+    - macros # Use variables and macros
+```
+
+### API Documentation
+
+```yaml
+markdown_extensions:
+    - pymdownx.highlight:
+          linenums: true
+    - pymdownx.superfences:
+          custom_fences:
+              - name: mermaid
+                class: mermaid
+                format: !!python/name:pymdownx.superfences.fence_code_format
+```
+
+### Multi-language Docs
+
+```yaml
+plugins:
+    - search:
+          lang:
+              - en
+              - es
+    - i18n:
+          default_language: en
+          languages:
+              en: English
+              es: Español
+```
+
+## Building and Deploying
+
+### Build Static Site
+
+```bash
+mkdocs build
+# Output in site/ directory
+```
+
+### Deploy to GitHub Pages
+
+```bash
+mkdocs gh-deploy
+# Builds and pushes to gh-pages branch
+```
+
+### CI/CD Example (.github/workflows/docs.yml)
+
+```yaml
+name: Deploy Docs
+on:
+    push:
+        branches: [main]
+
+jobs:
+    deploy:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-python@v5
+              with:
+                  python-version: 3.12
+            - run: pip install mkdocs mkdocs-material
+            - run: mkdocs gh-deploy --force
+```
+
+## Material Theme Features
+
+### Navigation
+
+```yaml
+theme:
+    features:
+        - navigation.instant # Instant loading
+        - navigation.sections # Group pages
+        - navigation.tabs # Top-level tabs
+        - toc.integrate # Integrated ToC
+```
+
+### Search
+
+```yaml
+theme:
+    features:
+        - search.suggest
+        - search.highlight
+```
+
+### Code Blocks
+
+```yaml
+markdown_extensions:
+    - pymdownx.highlight:
+          anchor_linenums: true
+    - pymdownx.inlinehilite
+    - pymdownx.snippets
+    - pymdownx.superfences
+```
+
+## Best Practices
+
+1. **Keep docs close to code** - Documentation in the same repo
+2. **Use includes** - Reuse content with `--8<--` includes
+3. **Add diagrams** - Use Mermaid for architecture diagrams
+4. **Version docs** - Use mike for multiple versions
+5. **Add search** - Always enable search plugin
+
+## Troubleshooting
+
+### Module not found after adding plugin
+
+Rebuild the container:
+
+- **VS Code:** `Cmd+Shift+P` → "Dev Containers: Rebuild Container"
+
+### MkDocs command not found
+
+Setup script may have failed. Run manually:
+
+```bash
+pip install --user mkdocs mkdocs-material
+```
+
+### Port 8000 already in use
+
+Change the port in mkdocs.yml:
+
+```yaml
+dev_addr: '0.0.0.0:8001'
+```
+
+And update devcontainer.json forwardPorts.
+
+## Related Overlays
+
+- **python** - For docs with custom Python scripts
+- **pre-commit** - Lint markdown before commits
+- **modern CLI tools** - ripgrep for searching docs
+
+## Resources
+
+- [MkDocs Documentation](https://www.mkdocs.org/)
+- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
+- [PyMdown Extensions](https://facelessuser.github.io/pymdown-extensions/)

package/overlays/mkdocs/devcontainer.patch.json

@@ -0,0 +1,24 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "ghcr.io/devcontainers-extra/features/mkdocs:2": {
+            "plugins": "mkdocs-material mkdocs-minify-plugin mkdocs-redirects pymdown-extensions"
+        }
+    },
+    "customizations": {
+        "vscode": {
+            "extensions": [
+                "yzhang.markdown-all-in-one",
+                "DavidAnson.vscode-markdownlint",
+                "bierner.markdown-mermaid"
+            ]
+        }
+    },
+    "forwardPorts": [8000],
+    "portsAttributes": {
+        "8000": {
+            "label": "MkDocs Server",
+            "onAutoForward": "openBrowser"
+        }
+    }
+}

package/overlays/mkdocs/overlay.yml

@@ -0,0 +1,15 @@
+id: mkdocs
+name: MkDocs
+description: Material for MkDocs - professional documentation generator
+category: language
+supports: []
+requires:
+    - python
+suggests: []
+conflicts: []
+tags:
+    - documentation
+    - mkdocs
+    - python
+ports:
+    - 8000