dolgolyov.alexei
4cbce89129
Backend:
- Structured JSON logging (python-json-logger) with request ID correlation
- RequestIDMiddleware (server-generated UUID, no client trust)
- Global exception handlers: AppException, RequestValidationError, generic 500
— all return consistent {"error": {code, message, request_id}} format
- Async rate limiting with lock + stale key eviction on auth endpoints
- Health endpoint checks DB connectivity, returns version + status
- Custom exception classes (NotFoundException, ForbiddenException, etc.)
- OpenAPI docs with tag descriptions, conditional URL (disabled in production)
- LOG_LEVEL, DOCS_ENABLED, RATE_LIMIT_* settings added
Docker:
- Backend: multi-stage build (builder + runtime), non-root user, HEALTHCHECK
- Frontend: removed dead user, HEALTHCHECK directive
- docker-compose: restart policies, healthchecks, Redis service, named volumes
for uploads/PDFs, rate limit env vars forwarded
- Alembic migrations run only in Dockerfile CMD (removed from lifespan)
Nginx:
- server_tokens off
- CSP, Referrer-Policy, Permissions-Policy headers
- HSTS ready (commented, enable with TLS)
Config & Docs:
- .env.production.example with production-ready settings
- CLAUDE.md project conventions (structure, workflow, naming, how-to)
- .env.example updated with new variables
Review fixes applied:
- Rate limiter: async lock prevents race condition, stale key eviction
- Request ID: always server-generated (no log injection)
- Removed duplicate alembic migration from lifespan
- Removed dead app user from frontend Dockerfile
- Health check logs DB errors
- Rate limit env vars forwarded in docker-compose
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
81 lines
2.5 KiB
Markdown
81 lines
2.5 KiB
Markdown
# Phase 7: Hardening — Subplan
|
||
|
||
## Goal
|
||
|
||
Harden for production: structured JSON logging, request tracing, global error handling, Docker security (non-root, multi-stage, health checks), rate limiting stub, security headers, OpenAPI docs, production config, and project conventions file.
|
||
|
||
## Prerequisites
|
||
|
||
- Phase 6 completed
|
||
|
||
---
|
||
|
||
## Tasks
|
||
|
||
### A. Logging & Request Tracing (Tasks 1–3)
|
||
|
||
- [x] **A1.** Add `python-json-logger` to pyproject.toml. Create `backend/app/core/logging.py`.
|
||
- [x] **A2.** Create `backend/app/core/middleware.py`: RequestIDMiddleware (X-Request-ID header + contextvars).
|
||
- [x] **A3.** Register middleware in main.py.
|
||
|
||
### B. Global Error Handling (Tasks 4–5)
|
||
|
||
- [x] **B4.** Create `backend/app/core/exceptions.py`: AppException + common subclasses.
|
||
- [x] **B5.** Add global exception handlers in main.py.
|
||
|
||
### C. Rate Limiting (Task 6)
|
||
|
||
- [x] **C6.** Create `backend/app/core/rate_limit.py`: in-memory sliding window, add to auth endpoints. Add config settings.
|
||
|
||
### D. Health Check (Task 7)
|
||
|
||
- [x] **D7.** Expand `/api/v1/health` to check DB connectivity + return version.
|
||
|
||
### E. Docker Hardening (Tasks 8–11)
|
||
|
||
- [x] **E8.** Rewrite `backend/Dockerfile`: multi-stage, non-root user, HEALTHCHECK.
|
||
- [x] **E9.** Update `frontend/Dockerfile`: non-root user, HEALTHCHECK.
|
||
- [x] **E10.** Update `docker-compose.yml`: healthchecks, restart policies, Redis service.
|
||
- [x] **E11.** Update `docker-compose.dev.yml` if needed.
|
||
|
||
### F. Security Headers (Task 12)
|
||
|
||
- [x] **F12.** Update `nginx/nginx.conf`: CSP, Referrer-Policy, Permissions-Policy, server_tokens off.
|
||
|
||
### G. OpenAPI Docs (Task 13)
|
||
|
||
- [x] **G13.** Configure OpenAPI metadata, tags, conditional docs URL in main.py.
|
||
|
||
### H. Production Config (Tasks 14–15)
|
||
|
||
- [x] **H14.** Create `.env.production.example`.
|
||
- [x] **H15.** Add LOG_LEVEL, DOCS_ENABLED to config.py.
|
||
|
||
### I. Project Conventions (Task 16)
|
||
|
||
- [x] **I16.** Create `CLAUDE.md` with project structure, conventions, workflow docs.
|
||
|
||
### J. Verification (Tasks 17–18)
|
||
|
||
- [x] **J17.** Docker builds succeed, health checks pass, non-root verified.
|
||
- [x] **J18.** Frontend builds, OpenAPI docs accessible.
|
||
|
||
---
|
||
|
||
## Acceptance Criteria
|
||
|
||
1. Structured JSON logs with request_id correlation
|
||
2. Consistent error response format with request_id
|
||
3. Health endpoint checks DB + returns version
|
||
4. Docker: non-root, multi-stage, healthchecks, restart policies
|
||
5. Auth rate limiting (in-memory)
|
||
6. Security headers in nginx
|
||
7. OpenAPI docs in dev, hidden in production
|
||
8. .env.production.example and CLAUDE.md complete
|
||
|
||
---
|
||
|
||
## Status
|
||
|
||
**COMPLETED**
|