Add deployment verification, examples, and test coverage

.gitignore

@@ -150,3 +150,9 @@ checklink/cookies.txt
 
 # Quarto
 .quarto
+
+# Generated files from examples/tests
+Caddyfile
+proxy.conf
+docker-compose.yml
+Dockerfile

DEPLOYMENT_VERIFICATION.md

@@ -0,0 +1,379 @@
+# dockr Deployment Capabilities Verification
+
+This document verifies that dockr can handle typical deployment requirements for web applications, replacing traditional Dockerfiles, docker-compose, and hosting configurations.
+
+## ✓ Supported Deployment Scenarios
+
+### 1. Dockerfile Generation
+dockr provides a fluent Python API for building Dockerfiles without writing raw Dockerfile syntax.
+
+**Capabilities:**
+- ✓ All standard Dockerfile instructions (FROM, RUN, COPY, WORKDIR, EXPOSE, CMD, etc.)
+- ✓ Multi-stage builds (FROM with AS, COPY --from)
+- ✓ Environment variables and ARG support
+- ✓ Health checks
+- ✓ Volume declarations
+- ✓ User/permission management
+- ✓ Parsing existing Dockerfiles
+
+**Example:**
+```python
+from dockr.core import Dockerfile
+
+df = (Dockerfile()
+    .from_('python:3.12-slim')
+    .workdir('/app')
+    .copy('requirements.txt', '.')
+    .run('pip install -r requirements.txt')
+    .copy('.', '.')
+    .expose(8000)
+    .cmd(['uvicorn', 'main:app', '--host', '0.0.0.0'])
+)
+
+df.save('Dockerfile')
+df.build(tag='myapp:latest')
+```
+
+### 2. Docker Compose Orchestration
+dockr provides programmatic docker-compose file generation.
+
+**Capabilities:**
+- ✓ Service definitions
+- ✓ Network configuration
+- ✓ Volume management (named and bind mounts)
+- ✓ Environment variables
+- ✓ Port mappings
+- ✓ Service dependencies (depends_on)
+- ✓ Restart policies
+- ✓ Build context configuration
+- ✓ Loading existing compose files
+- ✓ CLI integration (up, down, logs, ps, etc.)
+
+**Example:**
+```python
+from dockr.compose import Compose
+
+dc = (Compose()
+    .svc('web', image='nginx', ports={80: 80})
+    .svc('db', image='postgres:15',
+         env={'POSTGRES_PASSWORD': 'secret'},
+         volumes={'pgdata': '/var/lib/postgresql/data'})
+    .network('backend')
+    .volume('pgdata')
+)
+
+dc.save('docker-compose.yml')
+dc.up(detach=True)
+```
+
+### 3. Reverse Proxy & HTTPS (Caddy)
+dockr includes first-class support for Caddy reverse proxy with automatic HTTPS.
+
+**Capabilities:**
+- ✓ Automatic HTTPS with Let's Encrypt
+- ✓ DNS challenge support (Cloudflare, DuckDNS, etc.)
+- ✓ Reverse proxy configuration
+- ✓ Multiple domain support
+- ✓ Cloudflare tunnel integration
+- ✓ CrowdSec security integration
+- ✓ Custom Caddyfile generation
+
+**Example:**
+```python
+from dockr.caddy import caddy, caddyfile
+
+# Generate Caddyfile
+Path('Caddyfile').write_text(
+    caddyfile('example.com', app='web', port=8000, dns='cloudflare')
+)
+
+# Or use in Compose
+dc = dc.svc('caddy', **caddy(
+    domain='example.com',
+    app='web',
+    port=8000,
+    email='admin@example.com',
+    dns='cloudflare'
+))
+```
+
+### 4. Reverse Proxy & HTTPS (SWAG/LinuxServer)
+dockr also supports SWAG (Secure Web Application Gateway) for complex reverse proxy needs.
+
+**Capabilities:**
+- ✓ SWAG/nginx-based reverse proxy
+- ✓ Let's Encrypt HTTPS
+- ✓ Multiple validation methods (http, dns, etc.)
+- ✓ Subdomain support (wildcard)
+- ✓ Cloudflare tunnel support
+- ✓ Docker mods integration
+- ✓ Automatic proxy configuration
+
+**Example:**
+```python
+from dockr.compose import swag, swag_conf
+
+dc = dc.svc('swag', **swag(
+    domain='example.com',
+    app='web',
+    port=8000,
+    validation='dns',
+    subdomains='wildcard',
+    mods=['auto-proxy', 'dashboard']
+))
+```
+
+### 5. Security Features
+
+**Capabilities:**
+- ✓ CrowdSec integration (IDS/IPS)
+- ✓ Cloudflare tunnel (zero-trust networking)
+- ✓ SSL/TLS automation
+- ✓ Network isolation
+- ✓ Secret management (via environment variables)
+
+### 6. Container Runtime Support
+
+**Capabilities:**
+- ✓ Docker
+- ✓ Podman (via DOCKR_RUNTIME environment variable)
+- ✓ Credential management for registries
+
+**Example:**
+```bash
+export DOCKR_RUNTIME=podman
+python deploy.py
+```
+
+### 7. Build & Deployment Workflow
+
+**Capabilities:**
+- ✓ Image building
+- ✓ Container running (detached/interactive)
+- ✓ Container management (stop, rm, logs)
+- ✓ Image management (list, remove)
+- ✓ Testing containers
+- ✓ Port mapping
+- ✓ Volume mounting
+- ✓ Network configuration
+
+**Example:**
+```python
+from dockr.core import *
+
+# Build image
+df.build(tag='myapp:latest')
+
+# Test image
+assert test('myapp:latest', 'python --version')
+
+# Run container
+run('myapp:latest', detach=True, ports={8000: 8000}, name='myapp-prod')
+
+# Check containers
+print(containers())
+
+# View logs
+print(logs('myapp-prod', n=50))
+
+# Stop and remove
+stop('myapp-prod')
+rm('myapp-prod')
+```
+
+## Common Deployment Patterns
+
+### Pattern 1: Simple Web App + Database
+
+```python
+from dockr.core import Dockerfile
+from dockr.compose import Compose
+
+# App Dockerfile
+df = (Dockerfile()
+    .from_('python:3.12-slim')
+    .workdir('/app')
+    .copy('requirements.txt', '.')
+    .run('pip install -r requirements.txt')
+    .copy('.', '.')
+    .expose(8000)
+    .cmd(['python', 'main.py'])
+)
+df.save()
+
+# Compose with DB
+dc = (Compose()
+    .svc('app', build='.', ports={8000: 8000}, depends_on=['db'])
+    .svc('db', image='postgres:15', 
+         env={'POSTGRES_PASSWORD': 'secret'},
+         volumes={'dbdata': '/var/lib/postgresql/data'})
+    .volume('dbdata')
+)
+dc.up(detach=True)
+```
+
+### Pattern 2: Microservices with Shared Database
+
+```python
+dc = (Compose()
+    .svc('api', build='./api', ports={8000: 8000}, depends_on=['db'])
+    .svc('worker', build='./worker', depends_on=['db', 'redis'])
+    .svc('redis', image='redis:7-alpine')
+    .svc('db', image='postgres:15', volumes={'pgdata': '/var/lib/postgresql/data'})
+    .network('backend')
+    .volume('pgdata')
+)
+```
+
+### Pattern 3: Full Production Stack with HTTPS
+
+```python
+from dockr.compose import Compose
+from dockr.caddy import caddy
+
+dc = (Compose()
+    # Application
+    .svc('app', build='.', depends_on=['db', 'redis'], networks=['web'])
+
+    # Database
+    .svc('db', image='postgres:15-alpine',
+         env={'POSTGRES_PASSWORD': '${DB_PASSWORD}'},
+         volumes={'pgdata': '/var/lib/postgresql/data'},
+         networks=['web'])
+
+    # Cache
+    .svc('redis', image='redis:7-alpine', networks=['web'])
+
+    # Reverse Proxy with HTTPS
+    .svc('caddy', **caddy(
+        domain='example.com',
+        app='app',
+        port=8000,
+        email='admin@example.com',
+        dns='cloudflare',
+        crowdsec=False
+    ))
+
+    # Infrastructure
+    .network('web')
+    .volume('pgdata')
+    .volume('caddy_data')
+    .volume('caddy_config')
+)
+
+dc.save()
+dc.up(detach=True)
+```
+
+### Pattern 4: Multi-Domain Hosting
+
+```python
+from dockr.caddy import caddyfile
+from pathlib import Path
+
+# Generate multi-domain Caddyfile
+caddy_config = """
+app1.example.com {
+    reverse_proxy app1:8000
+}
+
+app2.example.com {
+    reverse_proxy app2:9000
+}
+
+api.example.com {
+    reverse_proxy api:8080
+}
+"""
+
+Path('Caddyfile').write_text(caddy_config)
+
+dc = (Compose()
+    .svc('app1', build='./app1', networks=['web'])
+    .svc('app2', build='./app2', networks=['web'])
+    .svc('api', build='./api', networks=['web'])
+    .svc('caddy',
+         image='caddy:2',
+         ports=['80:80', '443:443'],
+         volumes={
+             './Caddyfile': '/etc/caddy/Caddyfile',
+             'caddy_data': '/data'
+         },
+         networks=['web'],
+         restart='unless-stopped')
+    .network('web')
+    .volume('caddy_data')
+)
+```
+
+## Typical Deployment Requirements Coverage
+
+| Requirement | Supported | Implementation |
+|------------|-----------|----------------|
+| Dockerfile creation | ✓ | `Dockerfile()` fluent API |
+| Multi-stage builds | ✓ | `.from_(as_='stage')`, `.copy(from_='stage')` |
+| Docker Compose | ✓ | `Compose()` fluent API |
+| Service dependencies | ✓ | `depends_on` parameter |
+| Persistent storage | ✓ | Named volumes and bind mounts |
+| Environment variables | ✓ | `env` parameter, supports `${VAR}` syntax |
+| Port mapping | ✓ | `ports` parameter |
+| Networks | ✓ | `.network()` method |
+| Reverse proxy | ✓ | Caddy and SWAG support |
+| HTTPS/SSL | ✓ | Automatic with Caddy/SWAG |
+| DNS validation | ✓ | Cloudflare, DuckDNS, etc. |
+| Cloudflare tunnels | ✓ | Built-in support |
+| Health checks | ✓ | `.healthcheck()` method |
+| Container management | ✓ | `run()`, `stop()`, `rm()`, `logs()` |
+| Image management | ✓ | `images()`, `rmi()` |
+| Testing | ✓ | `test()` function |
+| Podman support | ✓ | `DOCKR_RUNTIME` env var |
+| Credential management | ✓ | Built-in Docker config handling |
+
+## Key Advantages Over Traditional Approach
+
+1. **Single Language**: Everything in Python, no context switching between YAML, Dockerfile syntax, and Caddyfile
+2. **Type Safety**: Python's type system helps catch errors early
+3. **Reusability**: Functions and classes for common patterns
+4. **Programmatic**: Logic, loops, conditionals in your deployment code
+5. **Version Control**: Python modules are easier to version and review than multiple config files
+6. **Testing**: Can unit test deployment configurations
+7. **IDE Support**: Full autocomplete and documentation
+8. **Integration**: Easy to integrate with other Python tools and workflows
+
+## Limitations & Workarounds
+
+### Current Limitations:
+1. **Kubernetes**: No direct K8s support (Docker/Compose only)
+   - Workaround: Use for development, transition to K8s for production
+
+2. **Compose v3 Syntax**: May not support all v3 features
+   - Workaround: Use `DockerCompose` CLI wrapper for advanced features
+
+3. **Custom Reverse Proxy Config**: Limited to Caddy and SWAG templates
+   - Workaround: Generate custom Caddyfile strings manually
+
+### Recommended for:
+- ✓ Development environments
+- ✓ Small to medium production deployments
+- ✓ Single-server deployments
+- ✓ Docker Compose-based hosting
+- ✓ Prototypes and MVPs
+
+### Not recommended for:
+- ✗ Large-scale Kubernetes deployments (use dedicated K8s tools)
+- ✗ Complex orchestration requirements (use K8s or Swarm)
+- ✗ When team prefers traditional config files
+
+## Conclusion
+
+**dockr successfully replaces traditional Dockerfiles and docker-compose configurations** for typical web application deployments. It provides:
+
+1. ✓ Complete Dockerfile generation
+2. ✓ Full docker-compose orchestration
+3. ✓ Production-ready reverse proxy (Caddy/SWAG)
+4. ✓ Automatic HTTPS
+5. ✓ Security integrations (CrowdSec, Cloudflare)
+6. ✓ Database and cache support
+7. ✓ Development to production workflow
+
+The Python-based API is more maintainable, testable, and powerful than scattered configuration files, making it ideal for Python developers managing their own deployments.