chore: reorganize repository structure

- Move docker-compose files to .docker/compose/ - Move docker-entrypoint.sh to .docker/ - Move DOCKER.md to .docker/README.md - Move 16 implementation docs to docs/implementation/ - Delete test artifacts (block_test.txt, caddy_*.json) - Update all references in Dockerfile, Makefile, tasks, scripts - Add .github/instructions/structure.instructions.md for enforcement - Update CHANGELOG.md Root level reduced from 81 items to ~35 visible items.
2025-12-21 04:57:31 +00:00
parent af8384046c
commit 05c2045f06
44 changed files with 492 additions and 395 deletions
--- a/.docker/compose/README.md
+++ b/.docker/compose/README.md
@@ -0,0 +1,50 @@
+# Docker Compose Files
+
+This directory contains all Docker Compose configuration variants for Charon.
+
+## File Descriptions
+
+| File | Purpose |
+|------|---------|
+| `docker-compose.yml` | Main production compose configuration. Base services and production settings. |
+| `docker-compose.dev.yml` | Development overrides. Enables hot-reload, debug logging, and development tools. |
+| `docker-compose.local.yml` | Local development configuration. Standalone setup for local testing. |
+| `docker-compose.remote.yml` | Remote deployment configuration. Settings for deploying to remote servers. |
+| `docker-compose.override.yml` | Personal local overrides. **Gitignored** - use for machine-specific settings. |
+
+## Usage Patterns
+
+### Production Deployment
+
+```bash
+docker compose -f .docker/compose/docker-compose.yml up -d
+```
+
+### Development Mode
+
+```bash
+docker compose -f .docker/compose/docker-compose.yml \
+               -f .docker/compose/docker-compose.dev.yml up -d
+```
+
+### Local Testing
+
+```bash
+docker compose -f .docker/compose/docker-compose.local.yml up -d
+```
+
+### With Personal Overrides
+
+Create your own `docker-compose.override.yml` in this directory for personal
+configurations (port mappings, volume paths, etc.). This file is gitignored.
+
+```bash
+docker compose -f .docker/compose/docker-compose.yml \
+               -f .docker/compose/docker-compose.override.yml up -d
+```
+
+## Notes
+
+- Always use the `-f` flag to specify compose file paths from the project root
+- The override file is automatically ignored by git - do not commit personal settings
+- See project tasks in VS Code for convenient pre-configured commands
--- a/.docker/compose/docker-compose.dev.yml
+++ b/.docker/compose/docker-compose.dev.yml
@@ -0,0 +1,40 @@
+# Development override - use with: docker-compose -f docker-compose.yml -f docker-compose.dev.yml up
+
+services:
+  app:
+    image: ghcr.io/wikid82/charon:dev
+    # Development: expose Caddy admin API externally for debugging
+    ports:
+      - "80:80"
+      - "443:443"
+      - "443:443/udp"
+      - "8080:8080"
+      - "2019:2019"  # Caddy admin API (dev only)
+    environment:
+      - CHARON_ENV=development
+      - CPM_ENV=development
+      - CHARON_HTTP_PORT=8080
+      - CPM_HTTP_PORT=80
+      - CHARON_DB_PATH=/app/data/charon.db
+      - CHARON_FRONTEND_DIR=/app/frontend/dist
+      - CHARON_CADDY_ADMIN_API=http://localhost:2019
+      - CHARON_CADDY_CONFIG_DIR=/app/data/caddy
+      # Security Services (Optional)
+      # 🚨 DEPRECATED: Use GUI toggle in Security dashboard instead
+      #- CPM_SECURITY_CROWDSEC_MODE=disabled # ⚠️ DEPRECATED
+      #- CPM_SECURITY_CROWDSEC_API_URL= # ⚠️ DEPRECATED
+      #- CPM_SECURITY_CROWDSEC_API_KEY= # ⚠️ DEPRECATED
+      #- CPM_SECURITY_WAF_MODE=disabled
+      #- CPM_SECURITY_RATELIMIT_ENABLED=false
+      #- CPM_SECURITY_ACL_ENABLED=false
+      - FEATURE_CERBERUS_ENABLED=true
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro # For local container discovery
+      - crowdsec_data:/app/data/crowdsec
+      # Mount your existing Caddyfile for automatic import (optional)
+      # - ./my-existing-Caddyfile:/import/Caddyfile:ro
+      # - ./sites:/import/sites:ro # If your Caddyfile imports other files
+
+volumes:
+  crowdsec_data:
+    driver: local
--- a/.docker/compose/docker-compose.local.yml
+++ b/.docker/compose/docker-compose.local.yml
@@ -0,0 +1,57 @@
+services:
+  charon:
+    image: charon:local
+    container_name: charon
+    restart: unless-stopped
+    ports:
+      - "80:80"        # HTTP (Caddy proxy)
+      - "443:443"      # HTTPS (Caddy proxy)
+      - "443:443/udp"  # HTTP/3 (Caddy proxy)
+      - "8080:8080"    # Management UI (Charon)
+      - "2345:2345"    # Delve Debugger
+    environment:
+      - CHARON_ENV=development
+      - CHARON_DEBUG=1
+      - TZ=America/New_York
+      - CHARON_HTTP_PORT=8080
+      - CHARON_DB_PATH=/app/data/charon.db
+      - CHARON_FRONTEND_DIR=/app/frontend/dist
+      - CHARON_CADDY_ADMIN_API=http://localhost:2019
+      - CHARON_CADDY_CONFIG_DIR=/app/data/caddy
+      - CHARON_CADDY_BINARY=caddy
+      - CHARON_IMPORT_CADDYFILE=/import/Caddyfile
+      - CHARON_IMPORT_DIR=/app/data/imports
+      - CHARON_ACME_STAGING=false
+      - FEATURE_CERBERUS_ENABLED=true
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    cap_add:
+      - SYS_PTRACE
+    security_opt:
+      - seccomp:unconfined
+    volumes:
+      - charon_data:/app/data
+      - caddy_data:/data
+      - caddy_config:/config
+      - crowdsec_data:/app/data/crowdsec
+      - /var/run/docker.sock:/var/run/docker.sock:ro # For local container discovery
+      - ./backend:/app/backend:ro # Mount source for debugging
+      # Mount your existing Caddyfile for automatic import (optional)
+#      - <PATH_TO_YOUR_CADDYFILE>:/import/Caddyfile:ro
+#      - <PATH_TO_YOUR_SITES_DIR>:/import/sites:ro # If your Caddyfile imports other files
+    healthcheck:
+      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8080/api/v1/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+
+volumes:
+  charon_data:
+    driver: local
+  caddy_data:
+    driver: local
+  caddy_config:
+    driver: local
+  crowdsec_data:
+    driver: local
--- a/.docker/compose/docker-compose.remote.yml
+++ b/.docker/compose/docker-compose.remote.yml
@@ -0,0 +1,19 @@
+version: '3.9'
+
+services:
+  # Run this service on your REMOTE servers (not the one running Charon)
+  # to allow Charon to discover containers running there (legacy: CPMP).
+  docker-socket-proxy:
+    image: alpine/socat
+    container_name: docker-socket-proxy
+    restart: unless-stopped
+    ports:
+      # Expose port 2375.
+      # ⚠️ SECURITY WARNING: Ensure this port is NOT accessible from the public internet!
+      # Use a VPN (Tailscale, WireGuard) or a private local network (LAN).
+      - "2375:2375"
+    volumes:
+      # Give the proxy access to the host's Docker socket
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    # Forward TCP traffic from port 2375 to the internal Docker socket
+    command: tcp-listen:2375,fork,reuseaddr unix-connect:/var/run/docker.sock
--- a/.docker/compose/docker-compose.yml
+++ b/.docker/compose/docker-compose.yml
@@ -0,0 +1,67 @@
+services:
+  charon:
+    image: ghcr.io/wikid82/charon:latest
+    container_name: charon
+    restart: unless-stopped
+    ports:
+      - "80:80"        # HTTP (Caddy proxy)
+      - "443:443"      # HTTPS (Caddy proxy)
+      - "443:443/udp"  # HTTP/3 (Caddy proxy)
+      - "8080:8080"    # Management UI (Charon)
+    environment:
+      - CHARON_ENV=production # CHARON_ preferred; CPM_ values still supported
+      - TZ=UTC # Set timezone (e.g., America/New_York)
+      - CHARON_HTTP_PORT=8080
+      - CHARON_DB_PATH=/app/data/charon.db
+      - CHARON_FRONTEND_DIR=/app/frontend/dist
+      - CHARON_CADDY_ADMIN_API=http://localhost:2019
+      - CHARON_CADDY_CONFIG_DIR=/app/data/caddy
+      - CHARON_CADDY_BINARY=caddy
+      - CHARON_IMPORT_CADDYFILE=/import/Caddyfile
+      - CHARON_IMPORT_DIR=/app/data/imports
+      # Security Services (Optional)
+      # 🚨 DEPRECATED: CrowdSec environment variables are no longer used.
+      # CrowdSec is now GUI-controlled via the Security dashboard.
+      # Remove these lines and use the GUI toggle instead.
+      # See: https://wikid82.github.io/charon/migration-guide
+      #- CERBERUS_SECURITY_CROWDSEC_MODE=disabled # ⚠️ DEPRECATED - Use GUI toggle
+      #- CERBERUS_SECURITY_CROWDSEC_API_URL= # ⚠️ DEPRECATED - External mode removed
+      #- CERBERUS_SECURITY_CROWDSEC_API_KEY= # ⚠️ DEPRECATED - External mode removed
+      #- CERBERUS_SECURITY_WAF_MODE=disabled # disabled, enabled
+      #- CERBERUS_SECURITY_RATELIMIT_ENABLED=false
+      #- CERBERUS_SECURITY_ACL_ENABLED=false
+      # Backward compatibility: CPM_ prefixed variables are still supported
+      # 🚨 DEPRECATED: Use GUI toggle instead (see Security dashboard)
+      #- CPM_SECURITY_CROWDSEC_MODE=disabled # ⚠️ DEPRECATED
+      #- CPM_SECURITY_CROWDSEC_API_URL= # ⚠️ DEPRECATED
+      #- CPM_SECURITY_CROWDSEC_API_KEY= # ⚠️ DEPRECATED
+      #- CPM_SECURITY_WAF_MODE=disabled
+      #- CPM_SECURITY_RATELIMIT_ENABLED=false
+      #- CPM_SECURITY_ACL_ENABLED=false
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    volumes:
+      - cpm_data:/app/data # existing data (legacy name); charon will also use this path by default for backward compatibility
+      - caddy_data:/data
+      - caddy_config:/config
+      - crowdsec_data:/app/data/crowdsec
+      - /var/run/docker.sock:/var/run/docker.sock:ro # For local container discovery
+      # Mount your existing Caddyfile for automatic import (optional)
+      # - ./my-existing-Caddyfile:/import/Caddyfile:ro
+      # - ./sites:/import/sites:ro # If your Caddyfile imports other files
+    healthcheck:
+      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8080/api/v1/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+
+volumes:
+  cpm_data:
+    driver: local
+  caddy_data:
+    driver: local
+  caddy_config:
+    driver: local
+  crowdsec_data:
+    driver: local