feat(infra): create staging docker-compose and environment configuration (#67)

This pull request introduces a production-grade, security-hardened Docker Staging environment configuration for **NexusReader**, prepared directly from the `develop` branch.

### 🚀 Key Additions

1. **`docker-compose.stage.yml`**:
   - Deploys five isolated containers (`nexus-web-stage`, `nexus-db-stage`, `nexus-qdrant-stage`, `nexus-neo4j-stage`) inside a dedicated `nexus-stage` bridge network.
   - Sets non-conflicting port mappings to allow staging to run concurrently with other environments on the same host (e.g., Web on `5080`, Postgres on `5438`, Neo4j HTTP on `7488`).
   - Configures robust container healthchecks (`curl` for Qdrant, `wget` for Neo4j, `pg_isready` for Postgres).
   - Maps dedicated named persistent volumes for databases (`pgdata_stage`, `qdrant_stage_data`, `neo4j_stage_data`) to prevent data loss.
   - Maps separate persistent volumes specifically for dynamic web uploads (`stage_www_uploads` for EPUBs, `stage_www_covers` for covers) without overriding the compiled static web client files.

2. **`.env.stage.template`**:
   - A clean deployment environment template providing a blueprint of all variables.
   - Copied to `.env.stage` locally during deployment to inject secrets securely.
   - Mandates a secure `NEXUS_ADMIN_PASSWORD` (checked by `DbInitializer` for staging/production builds).

3. **`.gitignore`**:
   - Explicitly ignores local environment configurations (such as `.env.stage`) to prevent accidentally committing credentials, while keeping the `.env.stage.template` tracked.

---

### 🧪 Verification Performed

- **Docker Compose Validation**: Ran `docker compose -f docker-compose.stage.yml --env-file .env.stage config` successfully with zero configuration or parsing errors.
- **Solution Compilation**: Ran `dotnet build NexusReader.slnx --no-restore` from root — **SUCCESS** with `0` compile errors.
- **Automated Tests**: Ran `dotnet test --no-restore` — **SUCCESS** (all 20/20 unit tests passed).

---------

Co-authored-by: Marek Jasiński <jasins.marek@gmail.com>
Reviewed-on: #67
Co-authored-by: Antigravity <antigravity@google.com>
Co-committed-by: Antigravity <antigravity@google.com>

.env.stage.template

@@ -0,0 +1,42 @@
+# ===================================================================
+# NexusReader — Staging (Stage) Environment Variables
+# ===================================================================
+# Copy this file to `.env.stage` and fill in the values before deployment:
+#   cp .env.stage.template .env.stage
+#
+# Then deploy with:
+#   docker compose -f docker-compose.stage.yml --env-file .env.stage up -d --build
+# ===================================================================
+
+# === PostgreSQL ===
+POSTGRES_USER=nexus_user_stage
+POSTGRES_PASSWORD=CHANGE_ME_TO_STRONG_PASSWORD
+POSTGRES_DB=nexus_stage_db
+POSTGRES_PORT=5438
+
+# === Neo4j ===
+NEO4J_USERNAME=neo4j
+NEO4J_PASSWORD=CHANGE_ME_TO_STRONG_PASSWORD
+
+# === Qdrant (leave empty to disable API key auth in staging) ===
+QDRANT_API_KEY=
+
+# === Web App ===
+WEB_PORT=5080
+
+# === Google OAuth (Staging credentials) ===
+GOOGLE_CLIENT_ID=placeholder_google_client_id_stage
+GOOGLE_CLIENT_SECRET=placeholder_google_client_secret_stage
+
+# === Gemini AI ===
+GOOGLE_AI_API_KEY=placeholder_gemini_api_key_stage
+
+# === Secure Admin Seed Password (MANDATORY in Staging environment) ===
+# This password is used by DbInitializer during startup. Cannot be empty or 'Admin123!'.
+NEXUS_ADMIN_PASSWORD=CHANGE_ME_TO_SECURE_ADMIN_PASSWORD
+
+# === Non-standard ports for auxiliary services ===
+QDRANT_HTTP_PORT=6383
+QDRANT_GRPC_PORT=6384
+NEO4J_HTTP_PORT=7488
+NEO4J_BOLT_PORT=7688

.gitignore

@@ -30,6 +30,7 @@ Thumbs.db
 
 .fake
 .env
+.env.stage
 src/NexusReader.Web/nexus.db
 src/NexusReader.Web/wwwroot/covers/
 src/NexusReader.Web/wwwroot/uploads/

docker-compose.stage.yml

@@ -0,0 +1,102 @@
+services:
+  db:
+    image: pgvector/pgvector:pg17
+    container_name: nexus-db-stage
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-nexus_user_stage}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
+      POSTGRES_DB: ${POSTGRES_DB:-nexus_stage_db}
+    ports:
+      - "${POSTGRES_PORT:-5438}:5432"
+    volumes:
+      - pgdata_stage:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER:-nexus_user_stage} -d $${POSTGRES_DB:-nexus_stage_db}"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+    networks:
+      - nexus-stage
+    restart: unless-stopped
+
+  web:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: nexus-web-stage
+    ports:
+      - "${WEB_PORT:-5080}:5000"
+    environment:
+      - ASPNETCORE_ENVIRONMENT=Staging
+      - ConnectionStrings__PostgresConnection=Host=db;Database=${POSTGRES_DB:-nexus_stage_db};Username=${POSTGRES_USER:-nexus_user_stage};Password=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
+      - ConnectionStrings__QdrantConnection=http://qdrant:6334
+      - ConnectionStrings__Neo4jConnection=bolt://neo4j:7687
+      - Neo4j__Username=${NEO4J_USERNAME:-neo4j}
+      - Neo4j__Password=${NEO4J_PASSWORD:?NEO4J_PASSWORD is required}
+      - Authentication__Google__ClientId=${GOOGLE_CLIENT_ID:-placeholder_google_client_id_stage}
+      - Authentication__Google__ClientSecret=${GOOGLE_CLIENT_SECRET:-placeholder_google_client_secret_stage}
+      - Ai__Google__ApiKey=${GOOGLE_AI_API_KEY:-placeholder_gemini_api_key_stage}
+      - NEXUS_ADMIN_PASSWORD=${NEXUS_ADMIN_PASSWORD:?NEXUS_ADMIN_PASSWORD is required}
+    depends_on:
+      db:
+        condition: service_healthy
+      qdrant:
+        condition: service_healthy
+      neo4j:
+        condition: service_healthy
+    volumes:
+      - stage_www_uploads:/app/wwwroot/uploads
+      - stage_www_covers:/app/wwwroot/covers
+    networks:
+      - nexus-stage
+    restart: unless-stopped
+
+  qdrant:
+    image: qdrant/qdrant:latest
+    container_name: nexus-qdrant-stage
+    environment:
+      - QDRANT__SERVICE__API_KEY=${QDRANT_API_KEY:-}
+    ports:
+      - "${QDRANT_HTTP_PORT:-6383}:6333"
+      - "${QDRANT_GRPC_PORT:-6384}:6334"
+    volumes:
+      - qdrant_stage_data:/qdrant/storage
+    healthcheck:
+      test: ["CMD-SHELL", "curl -sf http://localhost:6333/healthz || exit 1"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+    networks:
+      - nexus-stage
+    restart: unless-stopped
+
+  neo4j:
+    image: neo4j:5-community
+    container_name: nexus-neo4j-stage
+    environment:
+      - NEO4J_AUTH=${NEO4J_USERNAME:-neo4j}/${NEO4J_PASSWORD:?NEO4J_PASSWORD is required}
+    ports:
+      - "${NEO4J_HTTP_PORT:-7488}:7474"
+      - "${NEO4J_BOLT_PORT:-7688}:7687"
+    volumes:
+      - neo4j_stage_data:/data
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://localhost:7474 || exit 1"]
+      interval: 10s
+      timeout: 10s
+      retries: 10
+      start_period: 30s
+    networks:
+      - nexus-stage
+    restart: unless-stopped
+
+volumes:
+  pgdata_stage:
+  qdrant_stage_data:
+  neo4j_stage_data:
+  stage_www_uploads:
+  stage_www_covers:
+
+networks:
+  nexus-stage:
+    driver: bridge