init

CADDY_INTEGRATION.md

@@ -0,0 +1,261 @@
+# Caddy Integration Guide
+
+## Overview
+
+ASF TestArena is designed to work behind a Caddy reverse proxy for HTTPS and domain management.
+
+## Prerequisites
+
+- Caddy server running in Docker
+- Caddy network created
+- Domain name configured (testarena.nabd-co.com)
+
+## Step 1: Find Your Caddy Network Name
+
+Run this command to list all Docker networks:
+
+```bash
+docker network ls
+```
+
+Look for your Caddy network. Common names:
+- `caddy_network`
+- `caddy_default`
+- `caddy`
+- `proxy_network`
+
+## Step 2: Update docker-compose.yml
+
+### Option A: Edit the file directly
+
+Open `docker-compose.yml` and make these changes:
+
+1. Uncomment lines 28-29 at the bottom:
+```yaml
+networks:
+  testarena_network:
+    driver: bridge
+  caddy_network:  # ← Uncomment this line
+    external: true  # ← Uncomment this line
+```
+
+2. Replace `caddy_network` with your actual network name
+
+3. Add the network to the web service (around line 20):
+```yaml
+web:
+  build: .
+  container_name: testarena_web
+  environment:
+    # ... environment variables ...
+  volumes:
+    # ... volumes ...
+  depends_on:
+    - db
+  networks:
+    - testarena_network
+    - YOUR_CADDY_NETWORK_NAME  # ← Add this line with your network name
+  restart: unless-stopped
+```
+
+### Option B: Use this template
+
+Replace the entire `networks` section at the bottom with:
+
+```yaml
+networks:
+  testarena_network:
+    driver: bridge
+  YOUR_CADDY_NETWORK_NAME:
+    external: true
+```
+
+And update the web service networks:
+
+```yaml
+networks:
+  - testarena_network
+  - YOUR_CADDY_NETWORK_NAME
+```
+
+## Step 3: Configure Caddyfile
+
+Add this to your Caddyfile:
+
+```
+testarena.nabd-co.com {
+    reverse_proxy testarena_web:5000
+    
+    # Optional: Enable compression
+    encode gzip
+    
+    # Optional: Security headers
+    header {
+        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
+        X-Frame-Options "SAMEORIGIN"
+        X-Content-Type-Options "nosniff"
+        X-XSS-Protection "1; mode=block"
+    }
+    
+    # Optional: Logging
+    log {
+        output file /var/log/caddy/testarena.log
+        format json
+    }
+}
+```
+
+## Step 4: Reload Caddy
+
+After updating the Caddyfile:
+
+```bash
+docker exec -it caddy_container_name caddy reload --config /etc/caddy/Caddyfile
+```
+
+Or restart the Caddy container:
+
+```bash
+docker restart caddy_container_name
+```
+
+## Step 5: Start TestArena
+
+```bash
+docker-compose up -d --build
+```
+
+## Step 6: Verify
+
+1. Check that containers are running:
+```bash
+docker ps | grep testarena
+```
+
+2. Check that the web container is on both networks:
+```bash
+docker inspect testarena_web | grep -A 10 Networks
+```
+
+3. Test the connection:
+```bash
+curl -I https://testarena.nabd-co.com
+```
+
+## Troubleshooting
+
+### Error: "network not found"
+
+Your Caddy network name is incorrect. Double-check with:
+```bash
+docker network ls
+```
+
+### Error: "container not found"
+
+Make sure Caddy is running:
+```bash
+docker ps | grep caddy
+```
+
+### Can't access via domain
+
+1. Check DNS is pointing to your server
+2. Verify Caddy is running: `docker ps`
+3. Check Caddy logs: `docker logs caddy_container_name`
+4. Check TestArena logs: `docker-compose logs web`
+
+### 502 Bad Gateway
+
+The web container might not be ready:
+```bash
+docker-compose logs web
+```
+
+Wait a few seconds for the database to initialize.
+
+### Connection refused
+
+1. Verify the web service is on the Caddy network:
+```bash
+docker network inspect YOUR_CADDY_NETWORK_NAME
+```
+
+2. You should see `testarena_web` in the containers list
+
+## Network Architecture
+
+```
+Internet
+    ↓
+Caddy (HTTPS/443)
+    ↓
+testarena_web:5000 (Flask)
+    ↓
+testarena_db:5432 (PostgreSQL)
+```
+
+## Security Notes
+
+1. Caddy automatically handles HTTPS certificates via Let's Encrypt
+2. All traffic between Caddy and TestArena is on the internal Docker network
+3. Only Caddy needs to expose ports to the internet
+4. Database is only accessible within the testarena_network
+
+## Example: Complete docker-compose.yml
+
+```yaml
+version: '3.8'
+
+services:
+  db:
+    image: postgres:15-alpine
+    container_name: testarena_db
+    environment:
+      POSTGRES_DB: testarena
+      POSTGRES_USER: testarena_user
+      POSTGRES_PASSWORD: your_secure_password
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    networks:
+      - testarena_network
+    restart: unless-stopped
+
+  web:
+    build: .
+    container_name: testarena_web
+    environment:
+      DATABASE_URL: postgresql://testarena_user:your_secure_password@db:5432/testarena
+      SECRET_KEY: your_secret_key_here
+      FLASK_ENV: production
+    volumes:
+      - ./app:/app
+      - test_results:/app/test_results
+    depends_on:
+      - db
+    networks:
+      - testarena_network
+      - caddy_network  # ← Your Caddy network name
+    restart: unless-stopped
+
+volumes:
+  postgres_data:
+  test_results:
+
+networks:
+  testarena_network:
+    driver: bridge
+  caddy_network:  # ← Your Caddy network name
+    external: true
+```
+
+## Need Help?
+
+If you encounter issues:
+
+1. Share your Caddy network name
+2. Share any error messages from:
+   - `docker-compose logs web`
+   - `docker logs caddy_container_name`
+3. Verify network connectivity:
+   - `docker network inspect YOUR_CADDY_NETWORK_NAME`