Deployment

PinTeach runs on 4 services across 3 providers. All infrastructure is in EU regions for GDPR compliance.

Architecture Overview

pinteach.com          ─── Cloudflare Pages (Astro SSR)
app.pinteach.com      ─── Cloudflare Pages (React SPA, static)
api.pinteach.com      ─── Google Cloud Run (Fastify + BullMQ)
platform.pinteach.com ─── Cloudflare Pages (Starlight docs, static)

PostgreSQL            ─── Neon (serverless, Frankfurt)
Redis                 ─── Upstash (serverless, EU-West-1)
DNS + CDN             ─── Cloudflare
Container Registry    ─── Google Artifact Registry

---

Infrastructure

Neon PostgreSQL

Setting	Value
Provider	Neon
Version	PostgreSQL 16
Region	Frankfurt (eu-central-1)
Plan	Free tier (0.5 GB storage, autoscaling compute)
Tables	60 tables, 53 enums

Connection string format:

postgresql://<user>:<password>@<host>-pooler.<region>.aws.neon.tech/<database>?sslmode=require

Tip

Use the pooler endpoint (with -pooler in the hostname) for connection pooling. This is important for serverless environments like Cloud Run where connections scale up/down.

Database was initialized using drizzle-kit push --force instead of running migrations sequentially, since Neon starts with a clean database.

Upstash Redis

Setting	Value
Provider	Upstash
Region	EU-West-1
Protocol	rediss:// (TLS required)
Used for	BullMQ job queues, circuit breaker state, rate limiter counters

Connection string format:

rediss://default:<password>@<host>.upstash.io:6379

Caution

Note the rediss:// protocol (double s) — Upstash requires TLS. Using redis:// will fail silently.

---

Services

API — Google Cloud Run

Setting	Value
Provider	Google Cloud Run
Project	pinteach-api
Region	europe-west1 (Belgium)
Runtime	Bun (via oven/bun:1-slim Docker image)
Port	8080
Min instances	1 (required for BullMQ background workers)
Max instances	10
Memory	512 MiB
CPU	1
Domain	api.pinteach.com

Caution

min-instances=1 is critical. BullMQ workers (11 background jobs including crons) need a running instance at all times. Setting min to 0 would cause scheduled jobs to stop running when the service scales down.

Dockerfile

The API uses a 2-stage Docker build:

# Stage 1: Install + Build
FROM oven/bun:1 AS builder
WORKDIR /app
COPY package.json bun.lockb turbo.json ./
COPY apps/api/package.json ./apps/api/
COPY packages/db/package.json ./packages/db/
COPY packages/shared/package.json ./packages/shared/
COPY packages/email-templates/package.json ./packages/email-templates/
RUN bun install
COPY apps/api ./apps/api
COPY packages ./packages
COPY tsconfig*.json ./
RUN bun run build --filter=@pinteach/api --filter=@pinteach/shared \
    --filter=@pinteach/db --filter=@pinteach/email-templates

# Stage 2: Runtime
FROM oven/bun:1-slim
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/apps/api ./apps/api
COPY --from=builder /app/packages ./packages
COPY --from=builder /app/package.json ./
ENV PORT=8080
ENV HOST=0.0.0.0
EXPOSE 8080
CMD ["bun", "run", "apps/api/src/index.ts"]

Key details:

• .dockerignore excludes apps/web, apps/platform, .claude, .env*, node_modules
• Bun workspaces hoist all deps to root node_modules — no per-app node_modules directories
• Only API + shared packages are copied to the runtime stage

Deploy commands

# Set Python version for gcloud CLI (macOS)
export CLOUDSDK_PYTHON=/usr/local/bin/python3.12

# Build and deploy
gcloud builds submit --tag europe-west1-docker.pkg.dev/pinteach-api/pinteach/api
gcloud run deploy api \
  --image europe-west1-docker.pkg.dev/pinteach-api/pinteach/api \
  --region europe-west1 \
  --platform managed \
  --allow-unauthenticated \
  --min-instances 1 \
  --max-instances 10 \
  --memory 512Mi \
  --cpu 1 \
  --port 8080

Environment variables (Cloud Run)

Variable	Description
DATABASE_URL	Neon PostgreSQL connection string (pooler endpoint)
REDIS_URL	Upstash Redis connection string (rediss://)
APP_URL	https://app.pinteach.com
SESSION_SECRET	Cookie signing secret (min 32 chars)
GOOGLE_CLIENT_ID	Google OAuth client ID
GOOGLE_CLIENT_SECRET	Google OAuth client secret
GOOGLE_REDIRECT_URI	https://api.pinteach.com/api/auth/google/callback
STRIPE_SECRET_KEY	Stripe platform secret key
STRIPE_CONNECT_CLIENT_ID	Stripe Connect client ID
STRIPE_WEBHOOK_SECRET	Stripe webhook signing secret
RESEND_API_KEY	Resend email API key
NODE_ENV	production
PORT	8080
HOST	0.0.0.0
LOG_LEVEL	info

Domain mapping

api.pinteach.com is mapped via:

1. Google Cloud Run domain mapping (gcloud beta run domain-mappings create)
2. Cloudflare DNS: CNAME api → ghs.googlehosted.com (DNS only, not proxied)
3. SSL certificate provisioned by Google (takes 15-20 min on first setup)

Caution

The Cloudflare DNS record for api must be DNS only (gray cloud), NOT proxied (orange cloud). Proxying breaks Google’s SSL certificate validation.

---

Astro SSR — Cloudflare Pages (pinteach.com)

Setting	Value
Provider	Cloudflare Pages
Framework	Astro 5 + @astrojs/cloudflare adapter
Package	@pinteach/web
Domain	pinteach.com

Build configuration

Field	Value
Framework preset	Astro
Build command	bun install && bun run build --filter=@pinteach/web
Build output directory	apps/web/dist

Environment variables

Variable	Value
SKIP_DEPENDENCY_INSTALL	true
NODE_VERSION	22
API_URL	https://api.pinteach.com/api
APP_URL	https://app.pinteach.com

Tip

SKIP_DEPENDENCY_INSTALL=true prevents Cloudflare from running bun install --frozen-lockfile before the build command. The frozen lockfile fails because Bun workspaces require the root lockfile. Instead, bun install is included in the build command itself.

---

React SPA — Cloudflare Pages (app.pinteach.com)

Setting	Value
Provider	Cloudflare Pages
Framework	React 19 + Vite 6 (static SPA)
Package	@pinteach/app
Domain	app.pinteach.com

Build configuration

Field	Value
Framework preset	None
Build command	bun install && bun run build --filter=@pinteach/app
Build output directory	apps/app/dist

Environment variables

Variable	Value
SKIP_DEPENDENCY_INSTALL	true
NODE_VERSION	22
VITE_API_URL	https://api.pinteach.com/api
VITE_ASTRO_URL	https://pinteach.com

---

Platform Docs — Cloudflare Pages (platform.pinteach.com)

Setting	Value
Provider	Cloudflare Pages
Framework	Astro Starlight (static)
Package	@pinteach/platform
Domain	platform.pinteach.com

Build configuration

Field	Value
Framework preset	Astro
Build command	bun install && bun run build --filter=@pinteach/platform
Build output directory	apps/platform/dist

Environment variables

Variable	Value
SKIP_DEPENDENCY_INSTALL	true
NODE_VERSION	22

---

DNS Configuration (Cloudflare)

All DNS records for pinteach.com:

Type	Name	Target	Proxy
CNAME	api	ghs.googlehosted.com	DNS only (gray)
CNAME	app	<pages-project>.pages.dev	Proxied (orange)
CNAME	platform	<pages-project>.pages.dev	Proxied (orange)
CNAME	@ / root	<pages-project>.pages.dev	Proxied (orange)

Caution

The api subdomain must NOT be proxied through Cloudflare — Google Cloud Run manages its own SSL certificate and needs direct DNS resolution.

---

Cost Estimate (50 teachers/month)

Service	Plan	Estimated Cost
Neon PostgreSQL	Free → Launch ($19/mo)	$0 — $19/mo
Upstash Redis	Free (10K commands/day)	$0/mo
Google Cloud Run	1 min instance, 512 MiB	~$15 — $25/mo
Cloudflare Pages	Free (3 projects, unlimited bandwidth)	$0/mo
Google Artifact Registry	Container storage	~$1/mo
Total		~$16 — $45/mo

Scaling notes:

• Neon free tier includes 0.5 GB storage and 191 compute hours/month — enough for ~50 teachers
• Cloud Run min-instances=1 is the main fixed cost (~$15/mo)
• Cloudflare Pages has no bandwidth limits on the free plan
• Upstash free tier supports 10K commands/day — sufficient for BullMQ with 11 workers

---

Deployment Workflow

API (manual)

export CLOUDSDK_PYTHON=/usr/local/bin/python3.12

# Build + push Docker image
gcloud builds submit --tag europe-west1-docker.pkg.dev/pinteach-api/pinteach/api

# Deploy to Cloud Run
gcloud run deploy api \
  --image europe-west1-docker.pkg.dev/pinteach-api/pinteach/api \
  --region europe-west1

Frontend apps (automatic)

All 3 Cloudflare Pages projects auto-deploy on push to main:

• pinteach.com — rebuilds @pinteach/web
• app.pinteach.com — rebuilds @pinteach/app
• platform.pinteach.com — rebuilds @pinteach/platform

Database migrations

# From packages/db/
DATABASE_URL="<neon-connection-string>" bunx drizzle-kit migrate

Caution

Run migrations directly from packages/db/, not via bun run db:migrate from root — the turbo task may not pass environment variables through correctly.