refactor: simplify env configuration with single port definitions

- Update docker-compose.yml healthchecks to use env variables instead of hardcoded ports
- Restructure .env.example to define each port only once
- Auto-generate service URLs from port variables using ${PORT} syntax
- Document the configuration structure with clear sections
- Makes it easier to change ports without updating multiple variables

.env.example

@@ -1,4 +1,10 @@
 # Stripstream Librarian - Environment Configuration
+#
+# HOW TO USE:
+# 1. Copy this file to .env: cp .env.example .env
+# 2. Change the REQUIRED values below
+# 3. Optionally change ports if you have conflicts
+# 4. Run: docker-compose up --build
 
 # =============================================================================
 # REQUIRED - Change these values in production!
@@ -12,41 +18,38 @@ MEILI_MASTER_KEY=change-me-in-production
 API_BOOTSTRAP_TOKEN=change-me-in-production
 
 # =============================================================================
-# Services Configuration
+# Port Configuration (change only if you have port conflicts)
 # =============================================================================
 
-# API Service
-API_LISTEN_ADDR=0.0.0.0:8080
-API_BASE_URL=http://api:8080
+# Main application ports
 API_PORT=8080
-
-# Indexer Service  
-INDEXER_LISTEN_ADDR=0.0.0.0:8081
-INDEXER_SCAN_INTERVAL_SECONDS=5
 INDEXER_PORT=8081
-
-# Backoffice Web UI
 BACKOFFICE_PORT=8082
 
-# Meilisearch Search Engine
+# Infrastructure ports
 MEILI_PORT=7700
-
-# PostgreSQL Database
 POSTGRES_PORT=5432
 
 # =============================================================================
-# Database Configuration
+# Service URLs (auto-generated from ports above - don't change unless you know what you're doing)
 # =============================================================================
 
-# PostgreSQL connection string
-DATABASE_URL=postgres://stripstream:stripstream@postgres:5432/stripstream
+# API Service
+API_LISTEN_ADDR=0.0.0.0:${API_PORT}
+API_BASE_URL=http://api:${API_PORT}
 
-# =============================================================================
-# Search Configuration
-# =============================================================================
+# Indexer Service  
+INDEXER_LISTEN_ADDR=0.0.0.0:${INDEXER_PORT}
+INDEXER_SCAN_INTERVAL_SECONDS=5
 
-# Meilisearch connection URL
-MEILI_URL=http://meilisearch:7700
+# Backoffice Web UI
+# Uses BACKOFFICE_PORT from above
+
+# Meilisearch Search Engine
+MEILI_URL=http://meilisearch:${MEILI_PORT}
+
+# PostgreSQL Database
+DATABASE_URL=postgres://stripstream:stripstream@postgres:${POSTGRES_PORT}/stripstream
 
 # =============================================================================
 # Storage Configuration