config: move operational defaults to docker-compose.yml

- Add conversion service configuration with sensible defaults
  - BOOKHOARD_CONVERSION_CACHE_DIR: /app/cache/kepub
  - BOOKHOARD_CONVERSION_TOOL: /usr/bin/kepubify
  - BOOKHOARD_CONVERSION_CACHE_TTL: 24h
  - Add named volume for conversion cache
- Add rate limiting configuration with defaults
  - TEST_MODE: false
  - RATE_LIMIT_ENABLED: true
  - REQUESTS_PER_MINUTE: 10
- Simplify .env.example to only required secrets (JWT_SECRET, DBPASS)
- Add section comments to docker-compose.yml for better organization
- Document optional overrides in .env.example comments

This change separates secrets (in .env) from operational configuration
(in docker-compose.yml), following security best practices while
maintaining flexibility for custom deployments.

.env.example

@@ -1,5 +1,6 @@
 # Environment Variables
 # Copy this file to .env and update the values
+# Only secrets are required - all other settings have defaults in docker-compose.yml
 
 # JWT Secret for authentication (generate a secure random string)
 JWT_SECRET=your-secure-jwt-secret-key-here
@@ -7,22 +8,13 @@ JWT_SECRET=your-secure-jwt-secret-key-here
 # PostgreSQL database password
 DBPASS=your-secure-database-password-here
 
-# Test Mode Configuration (WARNING: Only set to true for integration testing)
-# When enabled, rate limiting is disabled to allow rapid test execution
-# Never enable in production environments
-TEST_MODE=false
-
-# Rate Limiting Configuration
-# Set to false to disable rate limiting (only for test environments)
-RATE_LIMIT_ENABLED=true
-# Number of requests allowed per minute per IP (default: 10)
-# Increase for integration testing (e.g., 1000)
-REQUESTS_PER_MINUTE=10
-
-# Conversion Service Configuration
-# Directory for caching converted files (KEPUB, etc.)
-BOOKHOARD_CONVERSION_CACHE_DIR=/var/bookhoard/cache/kepub
-# Conversion tool to use (kepubify or ebook-convert)
-BOOKHOARD_CONVERSION_TOOL=/usr/bin/kepubify
-# Cache TTL for converted files (e.g., 24h, 12h, 48h)
-BOOKHOARD_CONVERSION_CACHE_TTL=24h
+# Optional: Override Defaults (defaults are set in docker-compose.yml)
+# Test Mode: WARNING - Only set to true for integration testing
+# TEST_MODE=true
+# Rate Limiting: Disable or increase limits for testing
+# RATE_LIMIT_ENABLED=false
+# REQUESTS_PER_MINUTE=1000
+# Conversion Tool: Switch from kepubify to ebook-convert
+# BOOKHOARD_CONVERSION_TOOL=/usr/bin/ebook-convert
+# Conversion Cache TTL: Override default 24h
+# BOOKHOARD_CONVERSION_CACHE_TTL=48h

docker-compose.yml

@@ -1,6 +1,7 @@
 version: "3.8"
 
 services:
+  # PostgreSQL Database
   db:
     image: postgres:15-alpine
     container_name: bookhoard_db
@@ -16,22 +17,33 @@ services:
       timeout: 5s
       retries: 3
 
+  # Bookhoard Application
   app:
     build:
       context: .
       dockerfile: ./Dockerfile
     container_name: bookhoard
     environment:
+      # Database Configuration
       DATABASE_HOST: db
       DATABASE_PORT: 5432
       DATABASE_USER: postgres
       DATABASE_PASSWORD: ${DBPASS}
       DATABASE_NAME: bookhoard
+
+      # Application Configuration
       JWT_SECRET: ${JWT_SECRET}
       SERVER_PORT: 8765
+
+      # Rate Limiting Configuration
       TEST_MODE: ${TEST_MODE:-false}
       RATE_LIMIT_ENABLED: ${RATE_LIMIT_ENABLED:-true}
       REQUESTS_PER_MINUTE: ${REQUESTS_PER_MINUTE:-10}
+
+      # Conversion Service Configuration
+      BOOKHOARD_CONVERSION_CACHE_DIR: ${BOOKHOARD_CONVERSION_CACHE_DIR:-/app/cache/kepub}
+      BOOKHOARD_CONVERSION_TOOL: ${BOOKHOARD_CONVERSION_TOOL:-/usr/bin/kepubify}
+      BOOKHOARD_CONVERSION_CACHE_TTL: ${BOOKHOARD_CONVERSION_CACHE_TTL:-24h}
     ports:
       - "8765:8765"
     depends_on:
@@ -39,8 +51,13 @@ services:
         condition: service_healthy
     volumes:
       - ./uploads:/app/uploads
+      - bookhoard_conversion_cache:/app/cache/kepub
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U postgres"]
       interval: 5s
       timeout: 5s
       retries: 3
+
+# Named Volumes
+volumes:
+  bookhoard_conversion_cache: