Deployment Guide

Deploy your full-stack application using Docker, Vercel, and Render.

The starter ecosystem is designed for easy deployment to modern platforms, including Vercel for the frontend and Render or Railway for the API.

Core Concepts to Understand

[!IMPORTANT] Because the application secures authentication using HttpOnly Cookies, your domain setup must respect COOKIE_DOMAIN. Localhost handles this gracefully, but in production, both your UI (app.starter.xyz) and your API (api.starter.xyz) must align beneath a permissive cookie domain (.starter.xyz).

Hybrid Deployment (Vercel + Render/Railway)

This is a common professional setup: Vercel for the Frontend and Render/Railway for the API.

1. Frontend (Vercel)

1. Import the repository to Vercel.
2. Set Root Directory to apps/web.
3. Vercel will automatically detect the monorepo. Ensure the Build Command is: npx turbo build --filter=starter-web
4. Environment Variables:
   • NEXT_PUBLIC_API_URL: Your Render API URL (e.g., https://api.yourdomain.com).
   • Ensure Sync: Bring over SESSION_SECRET and ENCRYPTION_KEY.

2. Backend (Render/Railway)

1. Import the repository to Render or Railway.
2. Build Command: npm install && npx turbo build --filter=starter-api
3. Start Command: node apps/api/dist/index.js
4. Environment Variables:
   • MONGO_URI: Your production MongoDB connection string.
   • SESSION_SECRET: Must match the frontend secret.
   • ENCRYPTION_KEY: Must match the frontend key.
   • RESEND_API_KEY: Your Resend API key for production.

Docker Deployment

The project includes a Dockerfile and docker-compose.yml for self-hosting or running in a containerized environment.

1. Local Docker Setup

To run the entire ecosystem locally using Docker:

docker-compose up --build

2. Custom Dockerfile Configuration

The Dockerfile is optimized for Turborepo, using a multi-stage build process to keep images small and efficient.

# Dockerfile
FROM node:20-alpine AS base
# ... (rest of the Dockerfile)

3. Deploying to a Container Service

If you're deploying to a container service like AWS ECS or Google Cloud Run:

1. Build the Image: docker build -t your-image-name .
2. Push the Image: docker push your-image-name
3. Run the Container: Configure your container service to use the pushed image and set the necessary environment variables.

Post-Deployment Checklist

• Verify Domains: Ensure your frontend and API domains are correctly configured and aligned beneath a permissive cookie domain.
• Test Authentication: Verify that users can register, log in, and maintain sessions correctly.
• Monitor Performance: Use tools like Vercel Analytics or Sentry to monitor performance and catch errors in production.
• Update API Keys: Ensure any API keys used for external integrations are correctly configured and secured.