This document provides comprehensive deployment instructions for TendSocial across different platforms and environments.

Table of Contents

• Overview
• Local Development
• Frontend Deployment
• Backend Deployment
• Database Setup
• Environment Configuration
• Docker Deployment
• Production Checklist

---

Overview

TendSocial consists of two main components:

• Frontend: React + Vite application
• Backend: Fastify API server with Prisma ORM

Both can be deployed independently, making it flexible for various hosting scenarios.

---

Local Development

Prerequisites

• node.js 24.x
• pnpm 10.x
• Docker (optional, for container testing)
• Google Cloud API key

Initial Setup

# 1. Clone the repository
git clone https://github.com/marcmontecalvo/tendsocial.git
cd tendsocial

# 2. Install dependencies (root)
pnpm install

# 3. Set up environment variables
cp apps/frontend/.env.example apps/frontend/.env
cp apps/backend/.env.example apps/backend/.env
# Edit .env files with your credentials

# 4. Generate Prisma Client
pnpm db:generate

# 5. Run migrations (if needed)
pnpm db:migrate

Running Development Servers

# Start both frontend and backend
pnpm dev

# Or run individually
pnpm dev:marketing
pnpm dev:backend

---

Frontend Deployment

The frontend (apps/frontend) is a Vite application.

Option 1: Vercel (Recommended)

1. Import repository to Vercel.
2. Root Directory: apps/frontend
3. Build Command: pnpm build
4. Output Directory: dist
5. Environment Variables:
   • VITE_GOOGLE_API_KEY: Your Gemini API Key
   • VITE_API_URL: URL of your deployed backend

Option 2: Docker (Cloud Run)

The repository includes a production-optimized Dockerfile using turbo prune.

# Build image
docker build -f apps/frontend/Dockerfile -t tendsocial-web .

# Run locally
docker run -p 8080:80 tendsocial-web

---

Backend Deployment

The backend (apps/backend) is a Fastify server.

Option 1: Google Cloud Run (Recommended)

1. Build the image:

   gcloud builds submit --tag gcr.io/YOUR_PROJECT/tendsocial-api .

   Note: Run this from the repository root. The Dockerfile handles monorepo context.

2. Deploy:

   gcloud run deploy tendsocial-api \
     --image gcr.io/YOUR_PROJECT/tendsocial-api \
     --platform managed \
     --region us-central1 \
     --allow-unauthenticated \
     --set-env-vars="DATABASE_URL=...,JWT_SECRET=..."

Option 2: Docker (Generic)

# Build from root
docker build -f apps/backend/Dockerfile -t tendsocial-api .

# Run
docker run -p 4000:4000 \
  -e DATABASE_URL="..." \
  tendsocial-api

---

Database Setup

Production (PostgreSQL)

We recommend Neon (Serverless Postgres) or Google Cloud SQL.

1. Create a PostgreSQL database.
2. Get the connection string.
3. Set DATABASE_URL in your backend environment variables.
4. Run migrations:

   # From local machine (connecting to prod DB)
   DATABASE_URL="prod_url" pnpm db:migrate

---

Environment Configuration

Frontend (apps/frontend/.env)

VITE_GOOGLE_API_KEY=...
VITE_API_URL=...

Backend (apps/backend/.env)

DATABASE_URL="postgresql://..."
JWT_SECRET="..."
GOOGLE_API_KEY="..."
AWS_ACCESS_KEY_ID="..."
AWS_SECRET_ACCESS_KEY="..."
S3_BUCKET_NAME="..."
PORT=4000

---

Docker Deployment (Docker Compose)

For testing the full stack locally with Docker:

version: '3.8'

services:
  api:
    build:
      context: .
      dockerfile: apps/backend/Dockerfile
    ports:
      - "4000:4000"
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/tendsocial
    depends_on:
      - db

  web:
    build:
      context: .
      dockerfile: apps/frontend/Dockerfile
    ports:
      - "8080:80"

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_PASSWORD: password
      POSTGRES_DB: tendsocial

---

Production Checklist

Security

• [ ] All environment variables stored in secure secrets manager
• [ ] JWT secret is cryptographically random (min 32 characters)
• [ ] Database credentials rotated and secured
• [ ] HTTPS/TLS enabled on all endpoints
• [ ] CORS configured properly (not wildcard in production)
• [ ] Rate limiting enabled
• [ ] Input validation implemented (Zod schemas)
• [ ] SQL injection protection (Prisma ORM handles this)

Performance

• [ ] Database indexes created on frequently queried columns
• [ ] CDN configured for static assets
• [ ] Image optimization implemented
• [ ] API response caching where appropriate
• [ ] Database connection pooling configured
• [ ] Docker images optimized (multi-stage builds)

Monitoring

• [ ] Error tracking configured (Sentry/Bugsnag)
• [ ] Application logs centralized
• [ ] Uptime monitoring enabled
• [ ] Performance metrics tracked
• [ ] Database backups automated (see Backup & Restore)

Scalability

• [ ] Horizontal scaling plan documented
• [ ] Database read replicas configured (if needed)
• [ ] Job queue implemented for async tasks
• [ ] File storage moved to S3/R2
• [ ] Auto-scaling rules configured

Compliance

• [ ] Privacy policy updated
• [ ] Terms of service reviewed
• [ ] GDPR compliance measures implemented (if EU users)
• [ ] Data retention policies defined
• [ ] User data export functionality implemented

---

Troubleshooting

Common Issues

Build fails with "out of memory":

# Increase Node.js memory limit
NODE_OPTIONS="--max-old-space-size=4096" pnpm run build

Prisma connection issues:

# Verify database is accessible
pnpm exec prisma db pull

# Regenerate client
pnpm exec prisma generate

# Reset database (DESTRUCTIVE)
pnpm exec prisma migrate reset

CORS errors in production:

// backend/src/index.ts
await app.register(cors, {
  origin: process.env.CORS_ORIGIN || 'http://localhost:5173',
  credentials: true
});

Port already in use:

# Find process using port 4000
lsof -i :4000

# Kill process
kill -9 <PID>

---

Next Steps

• Review Architecture Overview for system design details
• Set up Backup & Restore procedures
• Implement monitoring per Tech Stack recommendations

---

Last Updated: November 2025
Maintainer: TendSocial Team