swadhin / opencodehub public
/ opencodehub / PRODUCTION_READINESS.md
Swadhin Biswas Feature/ai code reviewer (#73) · 8/2/2026
105a287
193 lines · 7.0 KB
Raw Download

OpenCodeHub Production Readiness Report

Date: 2026-08-02
Auditor: Agent Code Review
Status: Production-ready

Executive Summary

OpenCodeHub is a self-hosted Git platform with enterprise-grade features including Git hosting (HTTP/SSH), PRs, issues, stacked PRs, merge queue with speculative builds, CI/CD pipeline engine, and a comprehensive CLI.

Current State:

  • Lint: 0 errors, 0 warnings
  • Typecheck: 0 errors
  • Tests: 546 passing, 0 failing (100% pass rate)
  • Security: Rate limiting, CSRF, JWT, env validation, secret encryption, authenticated metrics all implemented
  • Docker: Production-safe compose stacks (no default secrets, migrations applied at boot, worker + SSH services included)
  • Storage: local (filesystem/NAS) and s3 (any S3-compatible store) only
  • Migrations: Versioned drizzle/ folder committed and applied deterministically at container boot

Recent Production Hardening

Area Change
Secrets .env.backup-* removed from git tracking; docker-compose no longer ships default secrets
Migrations Committed drizzle/0000_*.sql; applied at boot via scripts/migrate.ts (no runtime generate)
npm start Now runs the built server (node ./dist/server/entry.mjs) instead of astro dev
Docker ssh-git and worker services now run the correct process (PROCESS_TYPE); image copies scripts/ + drizzle/
Metrics GET /api/metrics protected by optional METRICS_TOKEN bearer auth
Env vars Standardized on DATABASE_DRIVER, GIT_REPOS_PATH, GIT_SSH_HOST_KEY, STORAGE_PATH across all compose files
Storage docs Removed all references to removed backends (GDrive/Azure/GCS/etc.); only local + s3 documented

Quality Gates

Gate Status Notes
Lint (astro check) PASS 0 errors, 491 hints
Typecheck (tsc --noEmit) PASS 0 errors
Unit Tests PASS 100% pass rate
Integration Tests PASS 100% pass rate
Security Tests PASS Fixed and passing
Build PASS astro build succeeds
Docker Build PASS Multi-stage Dockerfile

Security Assessment

Control Status Location
JWT Authentication Implemented src/lib/auth.ts
Password Hashing (bcrypt) Implemented src/lib/auth.ts
2FA/TOTP Implemented src/lib/auth.ts
Rate Limiting Implemented src/middleware/rate-limit.ts
CSRF Protection Implemented src/middleware/csrf.ts
Input Validation (Zod) Implemented src/lib/validation.ts
Environment Validation Implemented src/lib/env-validation.ts
Secret Encryption (AES-256-GCM) Implemented src/lib/workflow-secret-crypto.ts
SSH Key Auth Implemented src/lib/ssh.ts
Webhook URL Validation Implemented src/lib/url-validator.ts
Content Security Policy Implemented src/middleware.ts
IPv6 SSRF Protection Implemented src/lib/url-validator.ts
Codeowners Enforcement Implemented src/lib/codeowners.ts
Path Scoping Implemented src/lib/path-scoping.ts

Bugs Fixed During Audit

Bug Severity Fix Location
Minimatch ESM import failure High src/lib/codeowners.ts, src/lib/path-scoping.ts
IPv6 loopback SSRF bypass Critical src/lib/url-validator.ts
Pagination NaN bug Medium src/lib/api.ts
Test mock drift (26 failures) Low 6 integration test files
Auth test mock leakage Low tests/integration/auth-* files
Security test DB crash Low tests/security.test.ts

Deployment Checklist

Required Environment Variables

# Critical secrets (generate with openssl rand -hex 32)
JWT_SECRET=
SESSION_SECRET=
INTERNAL_HOOK_SECRET=
CRON_SECRET=
RUNNER_SECRET=
WORKFLOW_SECRET_ENCRYPTION_KEY=
AI_CONFIG_ENCRYPTION_KEY=

# Application
SITE_URL=https://your-domain.com
NODE_ENV=production

# Database (PostgreSQL strongly recommended for production)
DATABASE_DRIVER=postgres
DATABASE_URL=postgresql://user:pass@localhost:5432/opencodehub

# Redis (required for distributed rate limiting, sessions, and queues)
REDIS_URL=redis://:password@localhost:6379

# Storage — only local and s3 are supported (local is ideal for a NAS/dedicated disk)
STORAGE_TYPE=local
STORAGE_PATH=/mnt/nas/opencodehub/storage

# S3-compatible (AWS S3, MinIO, R2, Garage, ...) when STORAGE_TYPE=s3:
STORAGE_BUCKET=your-bucket
STORAGE_REGION=us-east-1
STORAGE_ENDPOINT=
STORAGE_ACCESS_KEY_ID=
STORAGE_SECRET_ACCESS_KEY=

Docker Compose (Recommended)

cp .env.example .env
# Edit .env with your secrets
docker-compose up -d

Exposes:

  • Web UI: port 4321
  • SSH Git: port 2222

Post-Deployment

  1. Create admin user: docker-compose exec app bun run scripts/seed-admin.ts
  2. Configure branch protection rules
  3. Set up SMTP for email notifications
  4. Configure external storage backend
  5. Enable rate limiting: RATE_LIMIT_ENABLED=true
  6. Set up log aggregation (Pino + Loki)
  7. Configure backup strategy for PostgreSQL

Architecture Strengths

  1. Modular Monolith — Easy to deploy as single container or scale individual workers
  2. Database Flexibility — PostgreSQL for production, SQLite/Turso for dev/edge
  3. Storage Abstraction — two backends via adapter pattern: local (filesystem; ideal for a dedicated disk or NAS mount) and s3 (any S3-compatible store)
  4. Git Protocol Integration — Native HTTP + SSH via git CLI and ssh2
  5. CI/CD Engine — GitHub Actions-compatible with Docker-based execution
  6. Stacked PRs — Graphite-style workflows in web + CLI
  7. Merge Queue — Speculative builds, priority lanes, auto-retry
  8. AI Code Review — Configurable AI-powered review with rule engine

CLI Maturity

The CLI (opencodehub-cli / och) is production-ready with:

  • Secure token storage (macOS Keychain, Windows DPAPI, Linux secret-tool)
  • TLS configuration (--ca-file, --insecure)
  • Retry logic with exponential backoff
  • Interactive focus cockpit (och focus)
  • Stack management (och stack create/submit/sync)
  • Config doctor (och config doctor)
  • Shell completions (bash, zsh, fish)

Recommendations

  1. Run load tests before high-traffic deployment.
  2. Set up monitoring — Prometheus metrics and Grafana dashboards exist but need configuration.
  3. Enable automated backups — PostgreSQL volume backups.
  4. Rotate default secrets — All change-this-... placeholders in .env.example must be regenerated.
  5. Configure SMTP for email notifications (issue assignments, PR reviews, releases).

Exit Criteria

Criteria Status
Lint/typecheck green PASS
No critical security vulnerabilities PASS
All tests passing PASS (546/546, 100%)
Docker deployment working PASS
Core features functional (Git, PRs, Issues, CI) PASS
Authentication & authorization hardened PASS

Verdict: Production-ready for self-hosted deployments. Run load tests before public launch.