feat: implement ci/cd pipeline with docker

.env.example

@@ -0,0 +1,61 @@
+# ----------------------------
+# Backend (FastAPI) - runtime
+# ----------------------------
+# Used by backend OAuth + GitHub sync on startup (GitHub OAuth endpoints).
+GITHUB_CLIENT_ID=your_client_id
+GITHUB_CLIENT_SECRET=your_client_secret
+
+# Used to sign/verify JWT access tokens issued by the API.
+# WARNING: Replace this with a long, random secret (>= 32 chars / 256 bits).
+# Example only (DO NOT use in production).
+JWT_SECRET=unsafe-example-jwt-secret-please-change
+
+# Database URL for SQLAlchemy async engine.
+# Examples:
+#   Postgres:
+#     postgresql+asyncpg://USER:PASSWORD@HOST:5432/DB
+#   SQLite:
+#     sqlite+aiosqlite:///./local.db
+#
+# Used by:
+# - `docker-compose.yml` via `DATABASE_URL`
+# - `deploy.yml` database migration job (`alembic upgrade head`)
+DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/solfoundry
+
+# Redis connection string.
+# Used by:
+# - `backend/app/services/websocket_manager.py` (Redis pub/sub for websockets)
+REDIS_URL=redis://localhost:6379/0
+
+# ----------------------------
+# Frontend (Vite) - build-time hints
+# ----------------------------
+# Used by some pages to construct absolute API URLs.
+# Many API calls use relative paths (`/api/...`), so this may be optional for some deployments.
+VITE_API_URL=http://localhost:8000
+VITE_WS_URL=ws://localhost:8000
+
+# ----------------------------
+# Docker Compose (local) - DB
+# ----------------------------
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=postgres
+POSTGRES_DB=solfoundry
+
+# ----------------------------
+# CI/CD (GitHub Actions) - deployment secrets
+# ----------------------------
+# These values must be set as GitHub repository secrets.
+
+# deploy.yml -> Vercel
+VERCEL_TOKEN=your_vercel_token
+VERCEL_ORG_ID=your_vercel_org_id
+VERCEL_PROJECT_ID=your_vercel_project_id
+
+# deploy.yml -> DigitalOcean Kubernetes
+DIGITALOCEAN_ACCESS_TOKEN=your_digitalocean_access_token
+DIGITALOCEAN_CLUSTER_NAME=your_digitalocean_cluster_name
+
+# deploy.yml -> frontend build injection
+# Used by the `deploy.yml` frontend build step (currently wired into the build environment).
+API_URL=https://api.solfoundry.org

.github/workflows/ci.yml

@@ -256,11 +256,87 @@ jobs:
         run: cargo fmt -- --check
         continue-on-error: true
 
+  # ==================== CONTAINER IMAGE BUILD CHECKS ====================
+  container-image-build:
+    name: Container Image Build (backend + frontend)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build backend image
+        run: docker build -t solfoundry-backend:test ./backend
+
+      - name: Build frontend image
+        run: docker build -t solfoundry-frontend:test ./frontend
+
+  # ==================== DOCKER COMPOSE SMOKE TEST ====================
+  # Spins up the full local stack and verifies basic readiness.
+  compose-smoke-test:
+    name: Compose Smoke Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Start stack (db + redis + backend + frontend)
+        env:
+          JWT_SECRET: smoke-test-jwt-secret-at-least-32-characters
+          GITHUB_CLIENT_ID: smoke-test-client-id
+          GITHUB_CLIENT_SECRET: smoke-test-client-secret
+        run: |
+          docker compose up -d --build db redis backend frontend
+
+      - name: Wait for health endpoints + verify DB/Redis/proxy/auth paths
+        run: |
+          set -euo pipefail
+          for i in {1..30}; do
+            if curl -fsS http://localhost:8000/health >/dev/null 2>&1; then
+              break
+            fi
+            sleep 2
+          done
+
+          BACKEND_HEALTH="$(curl -fsS http://localhost:8000/health)"
+          echo "$BACKEND_HEALTH"
+          BACKEND_HEALTH="$BACKEND_HEALTH" python - <<'PY'
+import json, os
+health = json.loads(os.environ["BACKEND_HEALTH"])
+assert health.get("database") == "ok", "database is not healthy"
+assert health.get("redis") == "ok", "redis is not healthy"
+assert health.get("status") == "ok", "overall backend health is not ok"
+print("backend health verified (database + redis)")
+PY
+
+          curl -fsS http://localhost:8081/health
+          # Verify that nginx -> backend proxying works.
+          curl -fsS "http://localhost:8081/api/leaderboard?limit=1" >/dev/null
+
+          # Minimal authenticated path exercise: protected endpoint should reject unauthenticated requests.
+          CODE="$(curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/api/auth/me)"
+          test "$CODE" = "401"
+
+      - name: Exercise backend schema initialization
+        run: |
+          docker compose exec -T backend python -c "import asyncio; from app.database import init_db; asyncio.run(init_db())"
+
+      - name: Ensure compose services are healthy
+        run: |
+          set -euo pipefail
+          docker inspect --format '{{json .State.Health.Status}}' solfoundry-db | rg '"healthy"'
+          docker inspect --format '{{json .State.Health.Status}}' solfoundry-redis | rg '"healthy"'
+          docker inspect --format '{{json .State.Health.Status}}' solfoundry-backend | rg '"healthy"'
+          docker inspect --format '{{json .State.Health.Status}}' solfoundry-frontend | rg '"healthy"'
+
+      - name: Tear down
+        if: always()
+        run: docker compose down -v
+
   # ==================== SUMMARY ====================
   ci-status:
     name: CI Status Summary
     runs-on: ubuntu-latest
-    needs: [backend-lint, backend-tests, frontend-lint, frontend-typecheck, frontend-tests, frontend-build, contracts-check, rust-lint]
+    needs: [backend-lint, backend-tests, frontend-lint, frontend-typecheck, frontend-tests, frontend-build, contracts-check, rust-lint, container-image-build, compose-smoke-test, backend-integration-postgres]
     if: always()
     steps:
       - name: Check CI Results
@@ -277,7 +353,74 @@ jobs:
           echo "| Frontend Build | ${{ needs.frontend-build.result }} |" >> $GITHUB_STEP_SUMMARY
           echo "| Contracts Check | ${{ needs.contracts-check.result }} |" >> $GITHUB_STEP_SUMMARY
           echo "| Rust Lint | ${{ needs.rust-lint.result }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| Container Image Build | ${{ needs.container-image-build.result }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| Compose Smoke Test | ${{ needs.compose-smoke-test.result }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| Backend Integration (Postgres) | ${{ needs.backend-integration-postgres.result }} |" >> $GITHUB_STEP_SUMMARY
 
       - name: Fail if any job failed
         if: contains(needs.*.result, 'failure')
-        run: exit 1
+        run: exit 1
+
+  # ==================== BACKEND POSTGRES INTEGRATION ====================
+  backend-integration-postgres:
+    name: Backend Integration (Postgres)
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: test
+          POSTGRES_PASSWORD: test
+          POSTGRES_DB: test
+        options: >-
+          --health-cmd="pg_isready -U test -d test"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=10
+    env:
+      PYTHONPATH: .
+      TEST_DATABASE_URL: postgresql+asyncpg://test:test@postgres:5432/test
+      SECRET_KEY: test-secret-key-for-ci
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install Dependencies
+        working-directory: backend
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install pytest pytest-asyncio
+
+      - name: Wait for Postgres
+        run: |
+          for i in {1..30}; do
+            if python - <<'PY'
+import os, sys, time
+import asyncpg, asyncio
+
+async def main():
+    url = os.environ["TEST_DATABASE_URL"]
+    try:
+        conn = await asyncpg.connect(url)
+        await conn.close()
+        return True
+    except Exception:
+        return False
+
+print(asyncio.run(main()))
+PY
+            then
+              break
+            fi
+            sleep 2
+          done
+
+      - name: Run DB-backed health test
+        working-directory: backend
+        run: pytest tests/test_logging_and_errors.py::test_health_check_format -v