Overview
Home Manager is a Next.js application that can be deployed to various platforms. This guide covers deployment to Vercel (recommended), Docker containers, and custom servers.
Prerequisites
Before deploying, ensure you have:
Database Setup
PostgreSQL database configured and accessible from your deployment platform. See Database Setup for detailed instructions.
Environment Variables
All required environment variables prepared:
DATABASE_URL
CLERK_SECRET_KEY
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
See Environment Variables for complete list.
Clerk Account
Clerk application configured with production keys. Update authorized domains in your Clerk Dashboard .
Deploy to Vercel (Recommended)
Vercel is the easiest deployment platform for Next.js applications, offering zero-configuration deployments with automatic HTTPS, global CDN, and serverless functions.
Quick Deploy
Connect Repository
Sign up at vercel.com
Click Add New Project
Import your Git repository (GitHub, GitLab, or Bitbucket)
Authorize Vercel to access your repository
Configure Project
Vercel auto-detects Next.js projects. Verify settings:
Framework Preset: Next.js
Root Directory: ./ (or your source directory)
Build Command: npm run build
Output Directory: .next (automatic)
Install Command: npm install
Set Environment Variables
In the project configuration:
Expand Environment Variables
Add each variable:
DATABASE_URL = postgresql://...
CLERK_SECRET_KEY = sk_live_...
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY = pk_live_...
Use production Clerk keys (starting with sk_live_ and pk_live_), not test keys.
Deploy
Click Deploy and wait for the build to complete (2-5 minutes). Vercel will:
Install dependencies
Run prisma generate (via postinstall)
Build Next.js application
Deploy to global CDN
Apply Database Migrations
After first deployment, run migrations: # Install Vercel CLI
npm i -g vercel
# Link project
vercel link
# Run migration
vercel env pull .env.production.local
npx prisma migrate deploy
Or push schema (for initial setup):
Configure Clerk Domain
Go to Clerk Dashboard
Select your application
Navigate to Domains
Add your Vercel domain (e.g., your-app.vercel.app)
Add custom domain if configured
Custom Domain Setup
Add Domain in Vercel
Go to your project Settings → Domains
Enter your custom domain (e.g., homemanager.example.com)
Click Add
Configure DNS
Add DNS records at your domain provider: Type: A
Name: @ (or subdomain)
Value: 76.76.21.21
Update Clerk
Add custom domain to Clerk’s allowed domains list.
Vercel automatically provisions SSL certificates and redirects HTTP to HTTPS.
Vercel CLI Deployment
Alternatively, deploy using the Vercel CLI:
# Install Vercel CLI
npm i -g vercel
# Login
vercel login
# Deploy to preview
vercel
# Deploy to production
vercel --prod
Deploy with Docker
Docker provides consistent deployment across any platform supporting containers.
Create Dockerfile
Create a Dockerfile in your project root:
# Multi-stage build for optimized image size
FROM node:20-alpine AS deps
RUN apk add --no-cache libc6-compat openssl
WORKDIR /app
# Install dependencies
COPY package.json package-lock.json* ./
RUN npm ci
# Generate Prisma Client
COPY prisma ./prisma/
RUN npx prisma generate
# Build application
FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
# Set environment variable for build
ENV NEXT_TELEMETRY_DISABLED=1
# Build Next.js
RUN npm run build
# Production image
FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
# Copy necessary files
COPY --from=builder /app/public ./public
COPY --from=builder /app/package.json ./package.json
# Copy built application
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
USER nextjs
EXPOSE 3000
ENV PORT=3000
ENV HOSTNAME= "0.0.0.0"
CMD [ "node" , "server.js" ]
Update next.config.ts
Enable standalone output for Docker:
import type { NextConfig } from "next" ;
const nextConfig : NextConfig = {
output: "standalone" , // Enable for Docker
};
export default nextConfig ;
Create .dockerignore
Dockerfile
.dockerignore
node_modules
.next
.git
.gitignore
npm-debug.log
README.md
.env*.local
.vercel
Build and Run
Build Docker Image
docker build -t home-manager:latest .
Run Container
docker run -p 3000:3000 \
-e DATABASE_URL="postgresql://..." \
-e CLERK_SECRET_KEY="sk_live_..." \
-e NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_live_..." \
home-manager:latest
Access Application
Open http://localhost:3000 in your browser.
Docker Compose Setup
For local development with PostgreSQL:
version : '3.8'
services :
db :
image : postgres:15-alpine
restart : always
environment :
POSTGRES_DB : homemanager
POSTGRES_USER : postgres
POSTGRES_PASSWORD : password
ports :
- "5432:5432"
volumes :
- postgres_data:/var/lib/postgresql/data
app :
build : .
restart : always
ports :
- "3000:3000"
environment :
DATABASE_URL : postgresql://postgres:password@db:5432/homemanager
CLERK_SECRET_KEY : ${CLERK_SECRET_KEY}
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY : ${NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY}
depends_on :
- db
volumes :
postgres_data :
Run with:
# Start services
docker-compose up -d
# Apply migrations
docker-compose exec app npx prisma migrate deploy
# View logs
docker-compose logs -f app
# Stop services
docker-compose down
Deploy to VPS/Custom Server
Deploy to any server running Node.js.
Requirements
Ubuntu 20.04+ or similar Linux distribution
Node.js 18+ installed
PostgreSQL 12+ installed or accessible
Nginx or Apache for reverse proxy
PM2 or systemd for process management
Deployment Steps
Clone Repository
# SSH into your server
ssh [email protected]
# Clone repository
git clone https://github.com/your-username/home-manager.git
cd home-manager
Configure Environment
# Create production environment file
nano .env.production.local
# Add variables:
DATABASE_URL = "postgresql://..."
CLERK_SECRET_KEY = "sk_live_..."
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY = "pk_live_..."
NODE_ENV = "production"
Setup Database
# Apply migrations
npx prisma migrate deploy
# Or push schema
npx prisma db push
Start with PM2
# Install PM2 globally
npm install -g pm2
# Start application
pm2 start npm --name "home-manager" -- start
# Save PM2 configuration
pm2 save
# Auto-start on system reboot
pm2 startup
Configure Nginx Reverse Proxy
/etc/nginx/sites-available/home-manager
server {
listen 80 ;
server_name homemanager.example.com;
location / {
proxy_pass http://localhost:3000;
proxy_http_version 1.1 ;
proxy_set_header Upgrade $ http_upgrade ;
proxy_set_header Connection 'upgrade' ;
proxy_set_header Host $ host ;
proxy_cache_bypass $ http_upgrade ;
proxy_set_header X-Real-IP $ remote_addr ;
proxy_set_header X-Forwarded-For $ proxy_add_x_forwarded_for ;
proxy_set_header X-Forwarded-Proto $ scheme ;
}
}
Enable site: sudo ln -s /etc/nginx/sites-available/home-manager /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
Setup SSL with Let's Encrypt
# Install Certbot
sudo apt install certbot python3-certbot-nginx
# Obtain certificate
sudo certbot --nginx -d homemanager.example.com
# Auto-renewal is configured automatically
PM2 Management Commands
# View application status
pm2 status
# View logs
pm2 logs home-manager
# Restart application
pm2 restart home-manager
# Stop application
pm2 stop home-manager
# Monitor resources
pm2 monit
# Update application
git pull
npm install
npm run build
pm2 restart home-manager
Railway
Create Project
Sign up at railway.app
Click New Project → Deploy from GitHub repo
Select your repository
Add PostgreSQL
Click New → Database → Add PostgreSQL
Database is automatically provisioned
DATABASE_URL is automatically added to environment
Configure Environment Variables
Add Clerk keys in Variables tab: CLERK_SECRET_KEY = sk_live_...
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY = pk_live_...
Deploy
Railway automatically deploys on push to main branch.
Render
Create Web Service
Sign up at render.com
Click New → Web Service
Connect your Git repository
Configure Service
Environment: Node
Build Command: npm install && npm run build
Start Command: npm start
Add PostgreSQL Database
Create separate PostgreSQL instance and link to web service.
Set Environment Variables
Add all required environment variables in service settings.
Netlify
Netlify has limited support for Next.js API routes. Use Vercel or other platforms for better Next.js support.
Post-Deployment Checklist
After deployment, verify everything works:
Continuous Deployment
GitHub Actions Example
.github/workflows/deploy.yml
name : Deploy to Production
on :
push :
branches : [ main ]
jobs :
deploy :
runs-on : ubuntu-latest
steps :
- uses : actions/checkout@v3
- name : Setup Node.js
uses : actions/setup-node@v3
with :
node-version : '20'
cache : 'npm'
- name : Install dependencies
run : npm ci
- name : Run linter
run : npm run lint
- name : Build application
run : npm run build
env :
DATABASE_URL : ${{ secrets.DATABASE_URL }}
CLERK_SECRET_KEY : ${{ secrets.CLERK_SECRET_KEY }}
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY : ${{ secrets.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY }}
- name : Deploy to Vercel
uses : amondnet/vercel-action@v20
with :
vercel-token : ${{ secrets.VERCEL_TOKEN }}
vercel-org-id : ${{ secrets.VERCEL_ORG_ID }}
vercel-project-id : ${{ secrets.VERCEL_PROJECT_ID }}
vercel-args : '--prod'
Troubleshooting
Build Fails
Error: Module not found or Cannot find moduleSolutions:
Delete node_modules and .next directories
Run npm install again
Check for missing dependencies in package.json
Ensure all imports use correct paths
Database Connection Issues
Error: Can't reach database serverSolutions:
Verify DATABASE_URL is correct
Check database server is running and accessible
Ensure IP allowlist includes your deployment platform
For Vercel, use connection pooling
Check firewall rules on VPS
Clerk Authentication Fails
Error: Clerk: Invalid publishable keySolutions:
Verify Clerk keys are for production environment
Check keys are set in environment variables
Ensure deployment domain is added to Clerk allowed domains
Restart application after updating environment variables
Application Crashes
Error: Application starts but crashes immediatelySolutions:
Check application logs for specific errors
Verify all environment variables are set
Ensure database migrations are applied
Check Node.js version compatibility (20+)
Increase memory limit if needed
Best Practices
Environment Separation Use different databases and Clerk keys for development, staging, and production.
Automated Backups Schedule regular database backups. Most cloud providers offer automated backup solutions.
Monitoring Set up error tracking (Sentry) and uptime monitoring to catch issues early.
CI/CD Pipeline Automate deployments with GitHub Actions or similar CI/CD tools.
Next Steps
Environment Variables Review all configuration options
Database Setup Advanced database configuration
API Reference Explore API endpoints