[Sub-issue #80-G]: CI/CD Integration + Documentation #87

New Issue

egullickson · 2026-02-03T02:19:32Z

egullickson commented

2026-02-03 02:19:32 +00:00

Parent Issue

Refs #80 - Unified Debug Logging System

Scope

Integrate logging configuration into CI/CD pipelines and update all documentation.

Files to Modify

.gitea/workflows/staging.yaml - Add generate-log-config.sh DEBUG
.gitea/workflows/production.yaml - Add generate-log-config.sh INFO
docs/UX-DEBUGGING.md - Replace with unified logging documentation
README.md - Update container count (5 → 9)
CLAUDE.md - Update architecture description

Implementation Details

CI/CD Integration

.gitea/workflows/staging.yaml addition:

jobs:
  deploy:
    steps:
      # ... existing steps ...
      - name: Generate logging configuration
        run: |
          ./scripts/ci/generate-log-config.sh DEBUG
          source .env.logging
      - name: Deploy containers
        run: |
          docker-compose --env-file .env.logging up -d

.gitea/workflows/production.yaml addition:

jobs:
  deploy:
    steps:
      # ... existing steps ...
      - name: Generate logging configuration
        run: |
          ./scripts/ci/generate-log-config.sh INFO
          source .env.logging
      - name: Deploy containers
        run: |
          docker-compose --env-file .env.logging up -d

Documentation Updates

docs/LOGGING.md (new, replaces UX-DEBUGGING.md):

# Unified Logging System

## Overview
MotoVaultPro uses a unified logging system with:
- Single LOG_LEVEL control variable
- Correlation IDs across all services
- Centralized aggregation with Grafana/Loki

## LOG_LEVEL Values

| Level | Frontend | Backend | PostgreSQL | Redis | Traefik |
|-------|----------|---------|------------|-------|---------|
| DEBUG | debug | debug | all queries | debug | DEBUG |
| INFO | info | info | DDL only | verbose | INFO |
| WARN | warn | warn | errors + slow | notice | WARN |
| ERROR | error | error | errors only | warning | ERROR |

## Correlation IDs

All logs include a `requestId` field (UUID v4) that traces requests across:
- Traefik (access logs)
- Backend (application logs)
- OCR (job logs)
- Frontend (browser console)

## Grafana Access

- URL: https://logs.motovaultpro.com
- Default credentials: admin/admin (change on first login)

### Example Queries

Query by requestId:

{container="mvp-backend"} |= "abc123-def456"


Query errors:

{container=~"mvp-.*"} | json | level="error"


## Environment Defaults

| Environment | LOG_LEVEL |
|-------------|-----------|
| Development | DEBUG |
| Staging | DEBUG |
| Production | INFO |

Acceptance Criteria

Staging deploys with LOG_LEVEL=DEBUG
Production deploys with LOG_LEVEL=INFO
docs/UX-DEBUGGING.md replaced with docs/LOGGING.md
README.md updated: "9-container architecture"
CLAUDE.md updated with logging architecture
All documentation accurate and complete

Dependencies

Depends on #80-A, #80-B, #80-C, #80-D, #80-E, #80-F

Milestone

Milestone 5: CI/CD + Documentation

## Parent Issue Refs #80 - Unified Debug Logging System ## Scope Integrate logging configuration into CI/CD pipelines and update all documentation. ## Files to Modify - `.gitea/workflows/staging.yaml` - Add generate-log-config.sh DEBUG - `.gitea/workflows/production.yaml` - Add generate-log-config.sh INFO - `docs/UX-DEBUGGING.md` - Replace with unified logging documentation - `README.md` - Update container count (5 → 9) - `CLAUDE.md` - Update architecture description ## Implementation Details ### CI/CD Integration **.gitea/workflows/staging.yaml** addition: ```yaml jobs: deploy: steps: # ... existing steps ... - name: Generate logging configuration run: | ./scripts/ci/generate-log-config.sh DEBUG source .env.logging - name: Deploy containers run: | docker-compose --env-file .env.logging up -d ``` **.gitea/workflows/production.yaml** addition: ```yaml jobs: deploy: steps: # ... existing steps ... - name: Generate logging configuration run: | ./scripts/ci/generate-log-config.sh INFO source .env.logging - name: Deploy containers run: | docker-compose --env-file .env.logging up -d ``` ### Documentation Updates **docs/LOGGING.md** (new, replaces UX-DEBUGGING.md): ```markdown # Unified Logging System ## Overview MotoVaultPro uses a unified logging system with: - Single LOG_LEVEL control variable - Correlation IDs across all services - Centralized aggregation with Grafana/Loki ## LOG_LEVEL Values | Level | Frontend | Backend | PostgreSQL | Redis | Traefik | |-------|----------|---------|------------|-------|---------| | DEBUG | debug | debug | all queries | debug | DEBUG | | INFO | info | info | DDL only | verbose | INFO | | WARN | warn | warn | errors + slow | notice | WARN | | ERROR | error | error | errors only | warning | ERROR | ## Correlation IDs All logs include a `requestId` field (UUID v4) that traces requests across: - Traefik (access logs) - Backend (application logs) - OCR (job logs) - Frontend (browser console) ## Grafana Access - URL: https://logs.motovaultpro.com - Default credentials: admin/admin (change on first login) ### Example Queries Query by requestId: ``` {container="mvp-backend"} |= "abc123-def456" ``` Query errors: ``` {container=~"mvp-.*"} | json | level="error" ``` ## Environment Defaults | Environment | LOG_LEVEL | |-------------|-----------| | Development | DEBUG | | Staging | DEBUG | | Production | INFO | ``` ## Acceptance Criteria - [ ] Staging deploys with LOG_LEVEL=DEBUG - [ ] Production deploys with LOG_LEVEL=INFO - [ ] docs/UX-DEBUGGING.md replaced with docs/LOGGING.md - [ ] README.md updated: "9-container architecture" - [ ] CLAUDE.md updated with logging architecture - [ ] All documentation accurate and complete ## Dependencies Depends on #80-A, #80-B, #80-C, #80-D, #80-E, #80-F ## Milestone Milestone 5: CI/CD + Documentation

egullickson added the

labels 2026-02-03 02:19:42 +00:00

egullickson referenced this issue

2026-02-03 02:19:57 +00:00

[Feature]: Implement Unified Debug Logging System with Centralized Log Aggregation #80

egullickson added

status

in-progress