Skip to main content

​
The Gap

Traceo had Terraform configs, CI/CD workflows, K8s manifests, Helm charts, docker-compose files, and a detailed TRACEO-PRODUCTION-READINESS-PLAN.md. What it didn’t have: a single document answering the question “how do I deploy this from scratch?” docs/deployment.md was created in Block 7.

​
Why It Matters More Than It Looks

A deployment guide is the document that gets read at the three highest-stakes moments in an early product:
  1. New engineer onboarding — the first day question is always “how do I run the thing.” Every hour spent piecing together the answer from scattered configs is an hour of trust eroded.
  2. Technical due diligence — investors and acquirers doing DD will ask for this. Its absence signals “hacker phase.” Its presence signals “production-ready thinking.”
  3. Incident response — when something breaks in production at 2am and the person on call didn’t set up the environment themselves, they need exactly this doc.

​
What Went In It

The Traceo deployment guide covers:
  • Architecture diagram (Vercel → Railway MCP/Engine → Neon)
  • Railway deployment for MCP Server and Engine with full env var tables
  • Vercel deployment for the web client with all NEXT_PUBLIC_* vars
  • Shared variables that must match across all services (BETTER_AUTH_SECRET, DATABASE_URL)
  • Migration instructions with the critical distinction: direct URL for DDL, pooled URL for apps
  • Neon branching for zero-downtime schema migrations
  • Verification commands

​
The Principle

Documentation that answers “how do I deploy this” is not tech debt cleanup. It’s infrastructure for the next person who joins. Write it while the context is hot — it took 30 minutes to write from memory after Block 7. It would have taken 3 hours to reconstruct from scratch a month later.