Deployment Overview

Learn about the deployment options available for ZeroStarter applications

ZeroStarter supports multiple deployment strategies to fit your infrastructure needs. Choose the deployment method that best matches your requirements.

Deployment Options

Vercel

Deploy to Vercel with zero configuration for both Next.js and Hono API

Docker

Containerized deployment with Docker and Docker Compose

Architecture Overview

ZeroStarter is built as a monorepo with two main services:

• Next.js Frontend (web/next) - React application running on port 3000
• Hono API Backend (api/hono) - API server running on port 4000

Both services share common packages:

• @packages/auth - Authentication logic using Better Auth
• @packages/db - Database schema and queries using Drizzle ORM
• @packages/env - Environment variable validation

Build System

The project uses Turborepo for efficient builds:

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**"]
    }
  }
}

Build Commands

Build All Services

turbo build

Environment Variables

Both deployment methods require proper environment configuration. See the Production Checklist for detailed environment setup.

Required Variables

Server Variables

• NODE_ENV - Set to production
• BETTER_AUTH_SECRET - Generate using openssl rand -base64 32
• POSTGRES_URL - PostgreSQL connection string
• HONO_APP_URL - Your API URL
• HONO_TRUSTED_ORIGINS - Comma-separated list of allowed origins

Client Variables

• NEXT_PUBLIC_APP_URL - Your application URL
• NEXT_PUBLIC_API_URL - Your API URL

OAuth Providers (Optional)

• GITHUB_CLIENT_ID - GitHub OAuth app ID
• GITHUB_CLIENT_SECRET - GitHub OAuth secret
• GOOGLE_CLIENT_ID - Google OAuth client ID
• GOOGLE_CLIENT_SECRET - Google OAuth secret

Database Setup

Before deploying, ensure your database is set up:

1. Generate migrations

   bun run db:generate
   
2. Run migrations

   bun run db:migrate
   
3. Verify with Drizzle Studio

   bun run db:studio
   

Choosing a Deployment Method

Use Vercel if you want:

• Fastest time to deployment
• Automatic preview deployments for PRs
• Built-in CI/CD
• Serverless architecture
• Easy scaling without infrastructure management

Use Docker if you want:

• Full control over infrastructure
• Self-hosted deployment
• Consistent environments across dev/staging/production
• Traditional server-based architecture
• Custom networking and security configurations

Next Steps

Vercel Deployment

Step-by-step guide for deploying to Vercel

Docker Deployment

Containerized deployment guide

Production Checklist

Essential production readiness checklist