Pipeline & Deploy

🚀 Pipeline & Deploy

Living Document - Questo documento descrive il flusso di deploy, le variabili d’ambiente e i provider esterni.

🌊 Git Flow

Branch Strategy

main (production)
  ↓
  ├── Direct commits (solo per hotfix)
  ├── Feature branches → PR → main
  └── Deploy automatico su Render

dev (development) - Neon Branch
  ↓
  ├── Testing & sperimentazione
  ├── Schema changes validation
  └── NO deploy automatico

Workflow Development

graph LR
    A[Local Development] --> B[Git Commit]
    B --> C[Git Push to main]
    C --> D[Render Auto-Deploy]
    D --> E[Production Live]

Steps:

1. Local Dev: Test su http://localhost:3000
2. Commit: git commit -m "feat: description"
3. Push: git push origin main
4. Auto-Deploy: Render rileva il push e fa rebuild
5. Live: in-1.ai, elements.blacktrails.io, ecc.

---

🏗️ Build & Deploy Pipeline

Render.com (Primary Host)

Web Service: blacktrails-platform
Region: Frankfurt (EU)
Plan: Starter ($7/month)
Auto-Deploy: Enabled on main branch push

Build Steps (Automatic)

# 1. Install dependencies
npm install

# 2. Build assets (if any)
# (Currently no build step - EJS templates)

# 3. Start server
npm start  # → node src/public/server.js

Build Time: ~2-3 minutes

Post-Deploy Health Check

# Render checks:
GET https://in-1.ai/health
# Expected: 200 OK + { status: "healthy" }

---

🔐 Environment Variables

Required Variables (Production)

Variable	Purpose	Provider	Example
DATABASE_URL	PostgreSQL connection (main)	Neon	postgresql://user:pass@ep-fancy-dust...
DATABASE_URL_DEV	PostgreSQL connection (dev)	Neon	postgresql://user:pass@ep-weathered-scene...
ANTHROPIC_API_KEY	Claude AI models	Anthropic	sk-ant-api03-...
RESEND_API_KEY	Email service	Resend	re_...
JWT_SECRET	Auth token signing	Self-generated	random-256-bit-string
SESSION_SECRET	Cookie encryption	Self-generated	random-256-bit-string
NODE_ENV	Environment	—	production
PORT	Server port	Render	10000 (auto-set)

Optional Variables

Variable	Purpose	Default
DB_SEARCH_PATH	Schema search order	auth,in1,elements,public
LOG_LEVEL	Logging verbosity	info
RATE_LIMIT_MAX	Rate limit max requests	100
RATE_LIMIT_WINDOW_MS	Rate limit window	900000 (15 min)

Local Development (.env)

# .env (DO NOT COMMIT TO GIT)
DATABASE_URL=postgresql://localhost:5432/blacktrails_local
DATABASE_URL_DEV=postgresql://user:pass@ep-weathered-scene...
ANTHROPIC_API_KEY=sk-ant-api03-...
RESEND_API_KEY=re_...
JWT_SECRET=local-dev-secret
SESSION_SECRET=local-dev-session-secret
NODE_ENV=development
PORT=3000

Security Note:

• Real credentials are stored in .env (gitignored)
• Production secrets are on Render dashboard
• Sensitive values are also in 1Password (BlackTrails Vault)

---

🌐 External Providers

Provider Matrix

Service	Purpose	Plan	Cost/Month	Critical
Neon.tech	PostgreSQL Database	Free (with limits)	€0	✅ Yes
Render.com	Web Service Hosting	Starter	$7	✅ Yes
Cloudflare	DNS, CDN, Pages	Free	€0	✅ Yes
Anthropic	AI Models (Claude)	Pay-as-you-go	~€50	✅ Yes
Resend	Transactional Email	Free (100/day)	€0	⚠️ Medium
GitHub	Code Repository	Free (private)	€0	✅ Yes
Vercel	Docs Hosting (future)	Free	€0	❌ No

---

📦 Deployment Targets

Multi-Brand Domains

Brand	Domain	Hosting	Deploy Trigger
IN-1	in-1.ai	Render	git push main
Elements	elements.blacktrails.io	Render	git push main
Forest	forest.blacktrails.io	Render	git push main
gCore	gcore.blacktrails.io	Render	git push main
BlackTrails	blacktrails.io	Render	git push main
Docs	docs.blacktrails.io	Cloudflare Pages	git push main (repo: blacktrails-docs)

Note: All brand subdomains run on the SAME Render instance (multi-brand monolith).

---

🔄 Library Sync Pipeline

Docs as Code Workflow

library/public/*.md (Git)
  ↓ (Manual trigger)
npm run sync-library
  ↓ (Parse frontmatter + MD5 hash)
PostgreSQL: library.documents
  ↓ (Generate embeddings - future)
PostgreSQL: library.embeddings (pgvector)
  ↓ (Semantic search)
AI RAG (IN-1, Forest, gCore)

Sync Script

Script: scripts/sync-library.js

Usage:

# Dry run (preview changes)
npm run sync-library -- --dry-run

# Sync to production
npm run sync-library

How it works:

1. Scans library/public/ for .md files
2. Parses YAML frontmatter (title, slug, category, author, etc.)
3. Calculates MD5 hash of content
4. Upserts into library.documents (create or update if hash changed)
5. Logs stats (created, updated, skipped, errors)

Triggers:

• Manual (via npm script)
• Future: Automatic on Git push (GitHub Actions webhook)

---

🧪 Testing & Verification

Pre-Deploy Checklist

# 1. Test locale
npm run dev
# → http://localhost:3000

# 2. Test IN-1 Rhama generation
# → http://localhost:3000/in1/rhama
# → Avvia esperienza, dialoga 4-5 turni, verifica Rhama

# 3. Test Elements booking
# → http://localhost:3000/elements
# → Verifica disponibilità camere

# 4. Verify database connection
npm run verify-production

Post-Deploy Verification

# 1. Check health endpoint
curl https://in-1.ai/health

# 2. Check Render logs
# → https://dashboard.render.com/web/[service-id]/logs

# 3. Test critical flows
# → IN-1 Rhama generation
# → Elements booking form
# → Forest gallery load

---

📜 Deploy Scripts

Available npm Scripts

{
  "scripts": {
    "start": "node src/public/server.js",
    "dev": "nodemon src/public/server.js",
    "verify-production": "node scripts/verify-production.js",
    "sync-library": "node scripts/sync-library.js",
    "generate-embeddings": "node scripts/generate-embeddings.js",
    "migrate:haiku-to-rhama": "node scripts/migrate-haiku-to-rhama.js",
    "setup-db": "node scripts/setup-production-db.js",
    "setup-db:prod": "node -r dotenv/config scripts/setup-production-db.js dotenv_config_path=.env.production",
    "translate-rhamas": "node scripts/translate-rhamas.js"
  }
}

Key Scripts Explained

Script	Purpose	Usage
npm start	Start production server	Auto-run by Render
npm run dev	Start dev server (nodemon)	Local development
npm run verify-production	Check DB connection & data	Pre/post-deploy
npm run sync-library	Sync docs to database	After doc changes
npm run setup-db	Create schemas & tables	Initial DB setup

---

🔥 Rollback Procedure

Emergency Rollback

If a deploy breaks production:

1. Revert commit:

git revert HEAD
git push origin main

2. Or: Rollback on Render:

   • Go to Render Dashboard
   • Select web service
   • Click “Manual Deploy”
   • Choose previous commit
   • Click “Deploy”

3. Or: Database rollback (Neon):

   • Go to Neon Console
   • Select blacktrails project
   • Click on main branch
   • Go to “Point in Time Restore”
   • Restore to timestamp before deploy

Recovery Time: ~5 minutes

---

🔔 Monitoring & Alerts

Current Setup (Manual)

• Logs: Render Dashboard → Logs tab
• Health Check: Manual curl to /health
• Database: Neon Console → Query Editor

Future: Automated Monitoring

• UptimeRobot: Ping /health every 5 minutes
• Sentry: Error tracking & alerts
• LogTail: Log aggregation
• Slack Webhook: Deploy notifications

---

🤖 Agent Update Instructions

AI Assistant: Quando il processo di deploy cambia (nuovi provider, variabili d’ambiente, script), esegui:

# 1. Analizza i file di configurazione
read_file E:\BLACKTRAILS-PLATFORM\package.json
read_file E:\BLACKTRAILS-PLATFORM\DEPLOY_CHECKLIST.md
list_dir E:\BLACKTRAILS-PLATFORM\scripts

# 2. Aggiorna questo file mantenendo:
#    - Tabella provider aggiornata
#    - Nuove variabili d'ambiente
#    - Nuovi script npm
#    - Workflow Git Flow (se cambia)

# 3. NON includere API keys reali (usa nomi variabili)

# 4. Commit con messaggio:
git commit -m "docs(truth): update pipeline flow"

---

Last Auto-Update: 2025-12-21
Next Review: On infrastructure change
Maintainer: BlackTrails AI Agent
Render Dashboard: dashboard.render.com
Neon Console: console.neon.tech