@mohanscodex/spectra-code 0.4.8 → 0.5.0

package/skills/render-deploy/references/codebase-analysis.md

@@ -0,0 +1,49 @@
+# Codebase Analysis (Deploy)
+
+Use this reference for framework-specific detection and build/start command selection when preparing a Render deployment.
+
+## Node.js Projects
+- Read `package.json` to detect framework (Express, Next.js, Nest.js, Fastify, etc.)
+- Check `scripts` section for build/start commands
+- Look for `engines` field for Node version, or look in `.node-versions` or `.nvmrc`
+- Detect package manager:
+  - `bun.lockb` (Bun) -> `bun install --frozen-lockfile` / `bun run start`
+  - `pnpm-lock.yaml` (pnpm) -> `pnpm install --frozen-lockfile` / `pnpm start`
+  - `yarn.lock` (Yarn) -> `yarn install --frozen-lockfile` / `yarn start`
+  - `package-lock.json` (npm) -> `npm ci` / `npm start`
+  - `package.json` only (npm fallback) -> `npm install` / `npm start`
+
+## Python Projects
+- Check for dependency files and detect package manager:
+  - `uv.lock` (uv) -> `uv sync` / `uv run gunicorn app:app`
+  - `poetry.lock` (Poetry) -> `poetry install --no-dev` / `poetry run gunicorn app:app`
+  - `Pipfile.lock` (pipenv) -> `pipenv install --deploy` / `pipenv run gunicorn app:app`
+  - `requirements.txt` (pip) -> `pip install -r requirements.txt` / `gunicorn app:app`
+  - `pyproject.toml` only -> check for `[tool.uv]`, `[tool.poetry]`, or use pip
+- Detect framework: Django, Flask, FastAPI, Celery, others
+- Check for Python version:
+  - `.python-version` (uv/pyenv)
+  - `runtime.txt` (Render-specific)
+  - `pyproject.toml` (requires-python field)
+
+## Go Projects
+- Read `go.mod` for dependencies
+- Identify web framework (Gin, Echo, Chi, Fiber, net/http)
+- Note Go version from `go.mod`
+
+## Static Sites
+- Look for build output directories (`build/`, `dist/`, `site/`, `public/`)
+- Detect framework: React, Vue, Gatsby, Next.js (static export)
+- Check build scripts in `package.json`
+
+## Docker Projects
+- Look for `Dockerfile`
+- Note exposed ports and build stages
+- Check for `docker-compose.yml` patterns
+
+## Key Information to Extract
+- Build command (e.g., `npm ci`, `pip install -r requirements.txt`, `go build`)
+- Start command (e.g., `npm start`, `gunicorn app:app`, `./bin/app`)
+- Environment variables used in code (API keys, database URLs, secrets)
+- Database requirements (PostgreSQL, Redis, MongoDB)
+- Port binding (check if app uses an environment variable for port to run on)

package/skills/render-deploy/references/configuration-guide.md

@@ -0,0 +1,603 @@
+# Render Configuration Guide
+
+Common configuration patterns, best practices, and troubleshooting for Render deployments.
+
+## Environment Variables
+
+### Required vs Optional Variables
+
+**Always declare ALL environment variables in render.yaml**, even if values are provided by user later.
+
+**Three categories:**
+
+1. **Configuration values** (hardcoded):
+```yaml
+envVars:
+  - key: NODE_ENV
+    value: production
+  - key: LOG_LEVEL
+    value: info
+  - key: API_URL
+    value: https://api.example.com
+```
+
+2. **Secrets** (user provides):
+```yaml
+envVars:
+  - key: JWT_SECRET
+    sync: false
+  - key: STRIPE_SECRET_KEY
+    sync: false
+  - key: API_KEY
+    sync: false
+```
+
+3. **Auto-generated** (Render provides):
+```yaml
+envVars:
+  - key: SESSION_SECRET
+    generateValue: true
+  - key: ENCRYPTION_KEY
+    generateValue: true
+```
+
+### Database Connection Patterns
+
+**PostgreSQL:**
+```yaml
+envVars:
+  - key: DATABASE_URL
+    fromDatabase:
+      name: postgres
+      property: connectionString
+```
+
+**Redis:**
+```yaml
+envVars:
+  - key: REDIS_URL
+    fromDatabase:
+      name: redis
+      property: connectionString
+```
+
+**Multiple databases:**
+```yaml
+envVars:
+  - key: PRIMARY_DB_URL
+    fromDatabase:
+      name: postgres-primary
+      property: connectionString
+  - key: ANALYTICS_DB_URL
+    fromDatabase:
+      name: postgres-analytics
+      property: connectionString
+  - key: CACHE_URL
+    fromDatabase:
+      name: redis
+      property: connectionString
+```
+
+### Cross-Service References
+
+Reference other services in your account:
+
+```yaml
+services:
+  - type: web
+    name: frontend
+    runtime: node
+    envVars:
+      - key: API_URL
+        fromService:
+          name: backend-api
+          type: web
+          property: host  # or hostport, port
+
+  - type: web
+    name: backend-api
+    runtime: node
+```
+
+**Available properties:**
+- `host`: Service hostname
+- `port`: Service port
+- `hostport`: Combined `host:port`
+
+### Environment Variable Groups
+
+Share common configuration across services:
+
+```yaml
+envVarGroups:
+  - name: common-config
+    envVars:
+      - key: NODE_ENV
+        value: production
+      - key: LOG_LEVEL
+        value: info
+      - key: TZ
+        value: UTC
+
+services:
+  - type: web
+    name: web-app
+    runtime: node
+    envVars:
+      - fromGroup: common-config
+      - key: PORT
+        value: 10000
+
+  - type: worker
+    name: worker
+    runtime: node
+    envVars:
+      - fromGroup: common-config
+```
+
+---
+
+## Port Binding
+
+### The Port Binding Requirement
+
+**CRITICAL:** Web services must bind to `0.0.0.0:$PORT`
+
+**Why this matters:**
+- Render sets `PORT` environment variable (default: 10000)
+- Services must bind to `0.0.0.0` (not `localhost` or `127.0.0.1`)
+- Health checks fail if port binding is incorrect
+- Deployment will fail or service won't receive traffic
+
+### Code Examples by Language
+
+**Node.js / Express:**
+```javascript
+const express = require('express');
+const app = express();
+
+const PORT = process.env.PORT || 3000;
+
+app.listen(PORT, '0.0.0.0', () => {
+  console.log(`Server running on port ${PORT}`);
+});
+```
+
+**Python / Flask:**
+```python
+import os
+from flask import Flask
+
+app = Flask(__name__)
+
+if __name__ == '__main__':
+    port = int(os.environ.get('PORT', 5000))
+    app.run(host='0.0.0.0', port=port)
+```
+
+**Python / Django:**
+
+In `settings.py`:
+```python
+# Django runs on port specified by environment
+ALLOWED_HOSTS = ['*']
+```
+
+Start command in render.yaml:
+```yaml
+startCommand: gunicorn config.wsgi:application --bind 0.0.0.0:$PORT
+```
+
+**Python / FastAPI:**
+```python
+import os
+import uvicorn
+from fastapi import FastAPI
+
+app = FastAPI()
+
+if __name__ == "__main__":
+    port = int(os.environ.get("PORT", 8000))
+    uvicorn.run(app, host="0.0.0.0", port=port)
+```
+
+Start command:
+```yaml
+startCommand: uvicorn main:app --host 0.0.0.0 --port $PORT
+```
+
+**Go:**
+```go
+package main
+
+import (
+    "fmt"
+    "net/http"
+    "os"
+)
+
+func main() {
+    port := os.Getenv("PORT")
+    if port == "" {
+        port = "3000"
+    }
+
+    http.HandleFunc("/", handler)
+    fmt.Printf("Server starting on port %s\n", port)
+    http.ListenAndServe(":"+port, nil)
+}
+```
+
+**Ruby / Rails:**
+
+In `config/puma.rb`:
+```ruby
+port ENV.fetch("PORT") { 3000 }
+bind "tcp://0.0.0.0:#{ENV.fetch('PORT', 3000)}"
+```
+
+**Rust / Actix:**
+```rust
+use actix_web::{App, HttpServer};
+use std::env;
+
+#[actix_web::main]
+async fn main() -> std::io::Result<()> {
+    let port = env::var("PORT").unwrap_or_else(|_| "8080".to_string());
+    let addr = format!("0.0.0.0:{}", port);
+
+    HttpServer::new(|| App::new())
+        .bind(&addr)?
+        .run()
+        .await
+}
+```
+
+---
+
+## Build Commands
+
+### Non-Interactive Flags
+
+**Always use non-interactive flags** to prevent builds from hanging waiting for input.
+
+**npm (Node.js):**
+```yaml
+buildCommand: npm ci
+# NOT: npm install
+```
+
+**pip (Python):**
+```yaml
+buildCommand: pip install -r requirements.txt
+# Already non-interactive
+```
+
+**apt (System packages):**
+```yaml
+buildCommand: apt-get update && apt-get install -y libpq-dev
+# Use -y flag to auto-confirm
+```
+
+**bundler (Ruby):**
+```yaml
+buildCommand: bundle install --jobs=4 --retry=3
+```
+
+### Build with Additional Steps
+
+**Node.js with build step:**
+```yaml
+buildCommand: npm ci && npm run build
+```
+
+**Python Django with static files:**
+```yaml
+buildCommand: pip install -r requirements.txt && python manage.py collectstatic --no-input
+```
+
+**Ruby Rails with assets:**
+```yaml
+buildCommand: bundle install && bundle exec rails assets:precompile
+```
+
+### Build Timeouts
+
+**Free tier:** 15 minutes
+**Paid tiers:** Configurable
+
+**If builds timeout:**
+1. Optimize dependencies (remove unused packages)
+2. Use build caching
+3. Consider pre-building in CI/CD
+4. Upgrade to paid tier for longer timeouts
+
+---
+
+## Database Connections
+
+### Internal vs External URLs
+
+**Use internal URLs for better performance:**
+
+When using `fromDatabase`, Render automatically provides internal `.render-internal.com` URLs:
+
+```yaml
+envVars:
+  - key: DATABASE_URL
+    fromDatabase:
+      name: postgres
+      property: connectionString
+```
+
+This provides: `postgresql://user:pass@postgres.render-internal.com:5432/db`
+
+**Benefits:**
+- Lower latency (same data center)
+- No external bandwidth charges
+- Automatic internal DNS
+
+### Connection Pooling
+
+**Node.js / PostgreSQL:**
+```javascript
+const { Pool } = require('pg');
+
+const pool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+  ssl: process.env.NODE_ENV === 'production' ? { rejectUnauthorized: false } : false,
+  max: 20, // Maximum pool size
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 2000,
+});
+```
+
+**Python / PostgreSQL:**
+```python
+import psycopg2.pool
+
+pool = psycopg2.pool.SimpleConnectionPool(
+    minconn=1,
+    maxconn=20,
+    dsn=os.environ['DATABASE_URL']
+)
+```
+
+**Django Settings:**
+```python
+DATABASES = {
+    'default': {
+        'ENGINE': 'django.db.backends.postgresql',
+        'URL': os.environ['DATABASE_URL'],
+        'CONN_MAX_AGE': 600,  # Connection pooling
+    }
+}
+```
+
+### Database Migrations
+
+**Run migrations during build:**
+
+**Django:**
+```yaml
+buildCommand: pip install -r requirements.txt && python manage.py migrate
+```
+
+**Rails:**
+```yaml
+buildCommand: bundle install && bundle exec rails db:migrate
+```
+
+**Node.js / Prisma:**
+```yaml
+buildCommand: npm ci && npx prisma migrate deploy
+```
+
+---
+
+## Free Tier Limitations
+
+### What's Included
+
+**Free tier provides:**
+- 1 web service
+- 1 PostgreSQL database (1 GB storage, 97 MB RAM)
+- 750 hours/month compute
+- 512 MB RAM per service
+- 0.5 CPU per service
+- 100 GB bandwidth/month
+
+### Resource Limits
+
+**Memory (512 MB):**
+- Monitor memory usage in logs
+- Optimize for memory-constrained environments
+- Use lightweight dependencies
+
+**CPU (0.5 cores):**
+- Suitable for low-traffic applications
+- Consider upgrading for higher traffic
+
+**Spin Down (Free services):**
+- Services spin down after 15 minutes of inactivity
+- First request after spin down takes ~30 seconds (cold start)
+- Upgrade to paid tier for always-on services
+
+### When to Upgrade
+
+**Upgrade to paid plan when:**
+- Need more than 1 web service
+- Need always-on services (no spin down)
+- Traffic exceeds free tier limits
+- Need more memory/CPU
+- Need faster build times
+- Need preview environments
+
+---
+
+## Health Checks
+
+### Adding Health Check Endpoints
+
+**Node.js / Express:**
+```javascript
+app.get('/health', (req, res) => {
+  res.status(200).json({
+    status: 'ok',
+    timestamp: new Date().toISOString()
+  });
+});
+```
+
+**Python / Flask:**
+```python
+@app.route('/health')
+def health():
+    return {'status': 'ok'}, 200
+```
+
+**Python / FastAPI:**
+```python
+@app.get("/health")
+async def health():
+    return {"status": "ok"}
+```
+
+**Go:**
+```go
+http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
+    w.WriteHeader(http.StatusOK)
+    w.Write([]byte(`{"status":"ok"}`))
+})
+```
+
+### Configure in render.yaml
+
+```yaml
+services:
+  - type: web
+    name: my-app
+    runtime: node
+    healthCheckPath: /health
+```
+
+**Benefits:**
+- Faster deployment detection
+- Better monitoring
+- Automatic restart on health check failures
+
+---
+
+## Common Deployment Issues
+
+### Issue 1: Missing Environment Variables
+
+**Symptom:** Service crashes with "undefined variable" errors
+
+**Solution:** Add all required env vars to render.yaml:
+```yaml
+envVars:
+  - key: DATABASE_URL
+    fromDatabase:
+      name: postgres
+      property: connectionString
+  - key: JWT_SECRET
+    sync: false  # User fills in Dashboard
+```
+
+### Issue 2: Port Binding Errors
+
+**Symptom:** `EADDRINUSE` or health check timeout errors
+
+**Solution:** Ensure app binds to `0.0.0.0:$PORT`:
+```javascript
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, '0.0.0.0');
+```
+
+### Issue 3: Build Hangs
+
+**Symptom:** Build times out after 15 minutes
+
+**Solution:** Use non-interactive build commands:
+```yaml
+buildCommand: npm ci  # NOT npm install
+```
+
+### Issue 4: Database Connection Fails
+
+**Symptom:** `ECONNREFUSED` on port 5432
+
+**Solutions:**
+1. Use `fromDatabase` for automatic internal URLs
+2. Enable SSL for external connections
+3. Check `ipAllowList` settings
+
+### Issue 5: Static Site 404s
+
+**Symptom:** Client-side routes return 404
+
+**Solution:** Add SPA rewrite rules:
+```yaml
+routes:
+  - type: rewrite
+    source: /*
+    destination: /index.html
+```
+
+### Issue 6: Out of Memory (OOM)
+
+**Symptom:** Service crashes with `JavaScript heap out of memory`
+
+**Solutions:**
+1. Optimize application memory usage
+2. Reduce dependency size
+3. Upgrade to higher plan with more RAM
+
+---
+
+## Best Practices Checklist
+
+**Environment Variables:**
+- [ ] All env vars declared in render.yaml
+- [ ] Secrets marked with `sync: false`
+- [ ] Database URLs use `fromDatabase` references
+
+**Port Binding:**
+- [ ] App binds to `process.env.PORT`
+- [ ] Bind to `0.0.0.0` (not `localhost`)
+
+**Build Commands:**
+- [ ] Use non-interactive flags (`npm ci`, `-y`, etc.)
+- [ ] Build completes under 15 minutes (free tier)
+
+**Start Commands:**
+- [ ] Command starts HTTP server correctly
+- [ ] Server binds to correct port
+
+**Health Checks:**
+- [ ] `/health` endpoint implemented
+- [ ] Returns 200 status code
+
+**Database:**
+- [ ] Connection pooling configured
+- [ ] Using internal URLs (`.render-internal.com`)
+- [ ] SSL enabled if needed
+
+**Plans:**
+- [ ] Using `plan: free` by default
+- [ ] Documented upgrade path for users
+
+**Git Repository:**
+- [ ] render.yaml committed to repository
+- [ ] Pushed to git remote (GitHub/GitLab/Bitbucket)
+- [ ] Branch specified in render.yaml (if not main)
+
+---
+
+## Additional Resources
+
+- Blueprint Specification: [blueprint-spec.md](blueprint-spec.md)
+- Service Types: [service-types.md](service-types.md)
+- Runtimes: [runtimes.md](runtimes.md)
+- Official Render Docs: https://render.com/docs