Seed & Source — Deployment Runbook

Seed & Source — Deployment Runbook

Audience: Technical founder / developer Last updated: 2026-03-14 Service ID: srv-d6mskc6a2pns73ddjlo0

---

Table of Contents

1. Architecture Overview
2. Deploy Process
3. Manual Deploy Override
4. Environment Variables Reference
5. Database Migrations
6. First Deploy Checklist
7. Rollback Procedure
8. Health Verification Protocol
9. Stripe Webhook Verification
10. Common Failure Modes + Remediation

---

1. Architecture Overview

The entire production stack runs as a single Render web service (AIO — All-in-One) built from Dockerfile.combined. nginx proxies internal ports and serves the React frontend.

Hard rule: The active AIO blueprint must contain exactly one paid web service (internal-admin). If a second type: web entry exists in internal-projects/internal-admin/render.yaml, Render will create a second billable service.

Service Map

Component	Internal Port	Public URL	Technology
license-server	8001	https://auth.seedsource.dev	FastAPI (Python)
admin-backend	8002	https://internal-admin.onrender.com	FastAPI (Python)
React frontend	static	served via nginx on port 80	Vite / React
nginx	80	(Render terminates TLS externally)	nginx

Request Flow

Client
  │
  ▼
Render TLS termination
  │
  ▼
nginx (port 80)
  ├── /api/license/*  → license-server (127.0.0.1:8001)
  ├── /api/admin/*    → admin-backend  (127.0.0.1:8002)
  ├── /webhooks/*     → license-server (127.0.0.1:8001)
  ├── /health         → license-server (127.0.0.1:8001)
  └── /*              → React static build

DNS

Domain	Target	Manager
seedsource.dev	Static landing (external)	External registrar
auth.seedsource.dev	CNAME → Render AIO service	External registrar

Key Files

File	Purpose
internal-projects/internal-admin/Dockerfile.combined	Multi-stage build for the AIO service
internal-projects/internal-admin/render.yaml	Render service definition + preDeployCommand
tooling/services/license-server/alembic/	Migration scripts

---

2. Deploy Process

Every push to main on the foundry-meta root triggers an automatic Render deploy. The full sequence is:

1. Push to main — Render detects the change via GitHub webhook.
2. Docker build — Render pulls the repo and runs docker build using Dockerfile.combined.
3. preDeployCommand runs — Before the new container serves traffic, Render executes:

   cd /app/license_server && alembic upgrade head

   This applies all pending migrations against the Neon production database. If this command fails, the deploy is aborted and the current version keeps serving.
4. Container swap — Render replaces the running container with zero downtime (rolling deploy).
5. Health check — Render hits the configured health check endpoint. If it fails, the deploy is marked failed and the previous container is preserved.

The migration step is automatic. You do not need to manually run alembic upgrade head after pushing.

---

3. Manual Deploy Override

Trigger a redeploy from the Render dashboard

1. Go to dashboard.render.com.
2. Select the internal-admin service (srv-d6mskc6a2pns73ddjlo0).
3. Click Manual Deploy → choose Deploy latest commit or Deploy specific commit.
4. Confirm — the same preDeployCommand flow runs.

Trigger via Render API

curl -X POST "https://api.render.com/v1/services/srv-d6mskc6a2pns73ddjlo0/deploys" \
  -H "Authorization: Bearer $RENDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"clearCache": false}'

Deploy a specific commit

COMMIT_SHA="<full-sha>"
curl -X POST "https://api.render.com/v1/services/srv-d6mskc6a2pns73ddjlo0/deploys" \
  -H "Authorization: Bearer $RENDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"commitId\": \"$COMMIT_SHA\", \"clearCache\": false}"

---

4. Environment Variables Reference

All variables are set in the Render dashboard under Environment for service srv-d6mskc6a2pns73ddjlo0. None of these are committed to the repository.

Variable	Description	Example / Format	Source
DATABASE_URL	Neon PostgreSQL connection string. Must use neondb_owner credential — app_user lacks DDL rights.	postgresql://neondb_owner:<pass>@<host>/neondb?sslmode=require	Neon dashboard → Connection Details
SECRET_KEY	Shared app/signing secret for license-server and shared flows. Min 32 chars.	openssl rand -hex 32	Generate locally
JWT_SECRET	Admin-backend JWT signing secret. Min 32 chars.	openssl rand -hex 32	Generate locally
GITHUB_CLIENT_ID	GitHub OAuth App client ID	Iv1.abc123...	GitHub → Settings → OAuth Apps
GITHUB_CLIENT_SECRET	GitHub OAuth App client secret	abc123...	GitHub → Settings → OAuth Apps
STRIPE_SECRET_KEY	Stripe live secret key	sk_live_...	Stripe dashboard → Developers → API Keys
STRIPE_WEBHOOK_SECRET	Webhook signing secret	whsec_...	Stripe dashboard → Webhooks → endpoint detail
STRIPE_PUBLISHABLE_KEY	Stripe live publishable key	pk_live_...	Stripe dashboard → Developers → API Keys
STRIPE_PRICE_ID_PRO_ALPHA	Price ID for Pro Alpha (MXN 580/mo)	price_...	Stripe dashboard → Products
STRIPE_PRICE_ID_PRO_MONTHLY	Price ID for Pro Monthly (MXN 980/mo)	price_...	Stripe dashboard → Products
STRIPE_PRICE_ID_PRO_ANNUAL	Price ID for Pro Annual (MXN 9,800/yr)	price_...	Stripe dashboard → Products
STRIPE_PRICE_ID_FEATURE_UNLOCK	Price ID for Feature Unlock (MXN 980 one-time)	price_...	Stripe dashboard → Products
LICENSE_SERVER_URL	Public auth host used by clients and checkout redirects.	https://auth.seedsource.dev	Render env
PAYMENT_SUCCESS_URL	Redirect after successful Stripe checkout	https://seedsource.dev/payment/success	Configure to match frontend route
PAYMENT_CANCEL_URL	Redirect after cancelled Stripe checkout	https://seedsource.dev/payment/cancel	Configure to match frontend route
CORS_ORIGINS	Comma-separated allowlist for browser origins.	https://internal-admin.onrender.com,https://auth.seedsource.dev	Render env

---

5. Database Migrations

How it works

The license-server uses Alembic for schema migrations. The migration chain lives at:

tooling/services/license-server/alembic/versions/

Current production head: 005_add_payment_feature_unlocked

Migrations run automatically via preDeployCommand in render.yaml before every deploy. The command is:

cd /app/license_server && alembic upgrade head

Check the current migration state

From the Render shell (service → Shell tab):

cd /app/license_server
alembic current

From a local machine with DATABASE_URL set:

cd tooling/services/license-server
DATABASE_URL="<neon_connection_string>" alembic current

Check migration history

cd /app/license_server
alembic history --verbose

Manually apply migrations (Render shell)

Only needed if preDeployCommand was bypassed or failed mid-run:

cd /app/license_server
alembic upgrade head

To apply a specific revision:

alembic upgrade 005_add_payment_feature_unlocked

Rollback a migration

⚠️ Irreversible on data. Downgrading migrations that drop columns or tables will destroy data. Take a Neon branch snapshot first.

# Roll back one step
alembic downgrade -1

# Roll back to a specific revision
alembic downgrade 004_<previous_revision_name>

# Roll back all migrations (empty schema)
alembic downgrade base

Create a new migration

cd tooling/services/license-server
alembic revision --autogenerate -m "describe_the_change"

Review the generated file in alembic/versions/ before committing. Autogenerate misses some changes (e.g., server defaults, check constraints) — always validate manually.

---

6. First Deploy Checklist

Use this for a net-new environment (e.g., staging, disaster recovery).

Pre-deploy

• Neon database created, neondb_owner credential copied
• DATABASE_URL set in Render with neondb_owner (not app_user)
• SECRET_KEY generated (openssl rand -hex 32) and set in Render
• JWT_SECRET generated (openssl rand -hex 32) and set in Render
• GitHub OAuth App created at https://github.com/settings/applications/new
  • Authorization callback URL: https://auth.seedsource.dev/auth/github/callback
  • GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET set in Render
• All 4 Stripe products created in dashboard; all 4 price IDs copied to Render env vars
• STRIPE_SECRET_KEY and STRIPE_PUBLISHABLE_KEY set (use live keys for prod)
• PAYMENT_SUCCESS_URL and PAYMENT_CANCEL_URL set and matching deployed frontend routes

DNS

• auth.seedsource.dev CNAME record points to the Render service’s .onrender.com hostname
• TLS certificate provisioned by Render (check service → Settings → Custom Domains — must show “Verified”)

Post-deploy (first time)

• Run health check (see §8)
• Register Stripe webhook endpoint (see §9)
• Set STRIPE_WEBHOOK_SECRET from the newly registered endpoint and redeploy
• Verify migrations: alembic current shows 005_add_payment_feature_unlocked (head)
• Test GitHub OAuth login end-to-end
• Trigger a test Stripe checkout session and confirm webhook receipt

---

7. Rollback Procedure

Render retains the last N deploy builds. Rolling back redeploys the previous image — the preDeployCommand (migrations) will NOT run in reverse automatically.

Steps

1. Go to Render dashboard → service srv-d6mskc6a2pns73ddjlo0 → Deploys.
2. Find the last known-good deploy.
3. Click Rollback to this deploy.
4. Confirm.

⚠️ Schema mismatch risk. If the current deploy added a migration, rolling back the code will leave the newer schema in Neon while running older code. Assess whether a manual alembic downgrade -1 is needed before rolling back — or ensure the old code is forward-compatible with the new schema.

Safe rollback sequence

# 1. Identify the migration the old code expects
#    (check alembic history in the old git commit)
git show <old-commit-sha>:tooling/services/license-server/alembic/versions/

# 2. If schema must be reverted, connect to Render shell on the CURRENT deploy
#    and downgrade BEFORE triggering the rollback
cd /app/license_server
alembic downgrade -1

# 3. Then trigger the rollback in the Render dashboard

---

8. Health Verification Protocol

Run this sequence after every deploy to confirm all subsystems are operational.

1. License server health

curl -s https://auth.seedsource.dev/health | jq .
# Expected: {"status":"healthy", ...}

2. License server API reachable

curl -s -o /dev/null -w "%{http_code}" https://auth.seedsource.dev/
# Expected: 200 or 404 (not 502/503)

3. Stripe webhook endpoint reachable

curl -s -o /dev/null -w "%{http_code}" \
  -X POST https://auth.seedsource.dev/webhooks/stripe
# Expected: 400 (missing signature — correct behavior, not 502/503/404)

4. React frontend served

curl -s -o /dev/null -w "%{http_code}" https://internal-admin.onrender.com/
# Expected: 200

5. Database connectivity (requires Render shell or local env)

cd /app/license_server
alembic current
# Expected: 005_add_payment_feature_unlocked (head)

6. Neon branch status

neonctl branches list
# Expected: main branch shows "ready"

Full one-liner health sweep

for URL in \
  "https://auth.seedsource.dev/health" \
  "https://internal-admin.onrender.com/"; do
  CODE=$(curl -s -o /dev/null -w "%{http_code}" "$URL")
  echo "$CODE  $URL"
done

---

9. Stripe Webhook Verification

Registered endpoint

https://auth.seedsource.dev/webhooks/stripe

Events subscribed (minimum required):

• checkout.session.completed
• customer.subscription.updated
• customer.subscription.deleted
• invoice.payment_failed

Verify endpoint is reachable

curl -s -o /dev/null -w "%{http_code}" \
  -X POST https://auth.seedsource.dev/webhooks/stripe
# Must return 400 — Stripe signature validation rejected (no sig header).
# 404 = route not registered. 502/503 = service down.

Register or update the webhook endpoint

1. Go to Stripe Dashboard → Developers → Webhooks.
2. Click Add endpoint.
3. URL: https://auth.seedsource.dev/webhooks/stripe
4. Select events listed above.
5. After saving, copy the Signing secret (whsec_...).
6. Set STRIPE_WEBHOOK_SECRET in Render and redeploy.

Test with Stripe CLI (local only)

stripe listen --forward-to http://localhost:8000/webhooks/stripe

stripe trigger checkout.session.completed \
  --override checkout_session:client_reference_id=1 \
  --override checkout_session:customer_email=user@example.com

Verify live webhook delivery in Stripe dashboard

Stripe Dashboard → Developers → Webhooks → select the endpoint → Recent deliveries. All checkout.session.completed events should show 200 responses.

---

10. Common Failure Modes + Remediation

10.1 — CORS 500 on all API responses

Symptom: Frontend receives 500 Internal Server Error on every API call. Stack trace mentions CORS middleware or missing env var accessed at startup.

Cause: An env var read at import-time (e.g., ALLOWED_ORIGINS, FRONTEND_URL) is missing, causing the CORS middleware to crash on every request.

Remediation:

1. Check Render logs: render logs srv-d6mskc6a2pns73ddjlo0 --tail 100
2. Identify the missing variable name in the traceback.
3. Add the variable in Render dashboard → Environment.
4. Trigger a manual redeploy.

---

10.2 — Missing column crash (UndefinedColumn / ProgrammingError)

Symptom: API returns 500; logs show UndefinedColumn: column "feature_unlocked" does not exist (or similar).

Cause: Code was deployed with a migration that didn’t apply, or preDeployCommand failed silently.

Remediation:

1. Open Render shell for the running service.
2. Run: cd /app/license_server && alembic current
3. If not at head, run: alembic upgrade head
4. If migration fails, check DATABASE_URL is using neondb_owner credential (see §10.6).

---

10.3 — Migration drift (alembic head doesn’t match DB)

Symptom: alembic current returns a revision behind head, or shows (detached).

Cause: Manual DB changes, a failed preDeployCommand, or conflicting migration branches.

Remediation:

# On Render shell:
cd /app/license_server
alembic history --verbose     # check the chain
alembic current               # see where DB is
alembic upgrade head          # apply missing revisions

If the schema is ahead of alembic (manual DDL was run directly on Neon):

alembic stamp <revision-id>   # mark DB as being at a specific revision

⚠️ alembic stamp does not run DDL — it only updates the alembic_version table. Use only when you are certain the schema matches the target revision.

---

10.4 — JWT_SECRET not set (all auth requests return 500)

Symptom: Every authenticated route returns 500; logs show KeyError: 'JWT_SECRET' or ValidationError on startup.

Cause: JWT_SECRET env var is missing from Render.

Remediation:

1. Generate a new secret locally: openssl rand -hex 32
2. Add to Render dashboard → Environment → JWT_SECRET.
3. Trigger redeploy.

Note: Rotating JWT_SECRET immediately invalidates all existing sessions. All logged-in users will need to re-authenticate.

---

10.5 — Unexpected second paid service appears in Render

Symptom: Blueprint apply creates internal-admin plus another service (for example license-server-rails).

Cause: render.yaml contains more than one type: web entry. Render always creates one billable service per entry.

Remediation:

1. Keep only one service block (internal-admin) in internal-projects/internal-admin/render.yaml.
2. Re-apply the blueprint in Render.
3. Delete any extra service created by the prior blueprint apply.
4. Verify both hosts still route correctly through the single AIO container:
   • https://auth.seedsource.dev/health
   • https://internal-admin.onrender.com/health

---

10.6 — Neon DDL permissions error (InsufficientPrivilege)

Symptom: alembic upgrade head fails with ERROR: permission denied for schema public or ERROR: must be owner of table.

Cause: DATABASE_URL is set to the app_user credential, which has read/write but NOT DDL (CREATE TABLE, ALTER TABLE, etc.) rights on Neon.

Remediation:

1. Go to Neon dashboard → your project → Connection Details.
2. Select the neondb_owner role (not app_user).
3. Copy the connection string.
4. Update DATABASE_URL in Render dashboard to use neondb_owner.
5. Trigger a redeploy — preDeployCommand will retry migrations.

Long-term note: Keep app_user for the application’s runtime queries and neondb_owner exclusively for migrations (alembic). Do not use neondb_owner as the application’s runtime credential.

---

Appendix: Useful Commands Quick Reference

# View live Render logs
render logs srv-d6mskc6a2pns73ddjlo0 --tail 200

# Check migration state (from Render shell)
cd /app/license_server && alembic current

# Apply all pending migrations (from Render shell)
cd /app/license_server && alembic upgrade head

# Roll back one migration (from Render shell)
cd /app/license_server && alembic downgrade -1

# Neon branch status
neonctl branches list

# Health check
curl -s https://auth.seedsource.dev/health | jq .

# Stripe webhook smoke test
curl -s -o /dev/null -w "%{http_code}" -X POST https://auth.seedsource.dev/webhooks/stripe
# → 400 is correct

# Trigger Render redeploy via API
curl -X POST "https://api.render.com/v1/services/srv-d6mskc6a2pns73ddjlo0/deploys" \
  -H "Authorization: Bearer $RENDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"clearCache": false}'