Skip to main content

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:
1

Database Setup

PostgreSQL database configured and accessible from your deployment platform.See Database Setup for detailed instructions.
2

Environment Variables

All required environment variables prepared:
  • DATABASE_URL
  • CLERK_SECRET_KEY
  • NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
See Environment Variables for complete list.
3

Clerk Account

Clerk application configured with production keys.Update authorized domains in your Clerk Dashboard.
Vercel is the easiest deployment platform for Next.js applications, offering zero-configuration deployments with automatic HTTPS, global CDN, and serverless functions.

Quick Deploy

1

Connect Repository

  1. Sign up at vercel.com
  2. Click Add New Project
  3. Import your Git repository (GitHub, GitLab, or Bitbucket)
  4. Authorize Vercel to access your repository
2

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
3

Set Environment Variables

In the project configuration:
  1. Expand Environment Variables
  2. 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.
4

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
5

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):
npx prisma db push
6

Configure Clerk Domain

  1. Go to Clerk Dashboard
  2. Select your application
  3. Navigate to Domains
  4. Add your Vercel domain (e.g., your-app.vercel.app)
  5. Add custom domain if configured

Custom Domain Setup

1

Add Domain in Vercel

  1. Go to your project SettingsDomains
  2. Enter your custom domain (e.g., homemanager.example.com)
  3. Click Add
2

Configure DNS

Add DNS records at your domain provider:
Type: A
Name: @ (or subdomain)
Value: 76.76.21.21
3

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:
Dockerfile
# 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:
next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "standalone", // Enable for Docker
};

export default nextConfig;

Create .dockerignore

.dockerignore
Dockerfile
.dockerignore
node_modules
.next
.git
.gitignore
npm-debug.log
README.md
.env*.local
.vercel

Build and Run

1

Build Docker Image

docker build -t home-manager:latest .
2

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
3

Access Application

Open http://localhost:3000 in your browser.

Docker Compose Setup

For local development with PostgreSQL:
docker-compose.yml
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

1

Clone Repository

# SSH into your server
ssh [email protected]

# Clone repository
git clone https://github.com/your-username/home-manager.git
cd home-manager
2

Install Dependencies

npm install
3

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"
4

Setup Database

# Apply migrations
npx prisma migrate deploy

# Or push schema
npx prisma db push
5

Build Application

npm run build
6

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
7

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
8

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

Deploy to Other Platforms

Railway

1

Create Project

  1. Sign up at railway.app
  2. Click New ProjectDeploy from GitHub repo
  3. Select your repository
2

Add PostgreSQL

  1. Click NewDatabaseAdd PostgreSQL
  2. Database is automatically provisioned
  3. DATABASE_URL is automatically added to environment
3

Configure Environment Variables

Add Clerk keys in Variables tab:
CLERK_SECRET_KEY=sk_live_...
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_...
4

Deploy

Railway automatically deploys on push to main branch.

Render

1

Create Web Service

  1. Sign up at render.com
  2. Click NewWeb Service
  3. Connect your Git repository
2

Configure Service

  • Environment: Node
  • Build Command: npm install && npm run build
  • Start Command: npm start
3

Add PostgreSQL Database

Create separate PostgreSQL instance and link to web service.
4

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:
1

Health Check

  • Application loads successfully
  • Sign in/sign up flow works
  • Dashboard loads without errors
  • Database connection is stable
2

Security

  • HTTPS enabled and working
  • Environment variables are secure
  • Database has strong password
  • Clerk production keys configured
  • Allowed domains configured in Clerk
3

Performance

  • Pages load quickly (under 3 seconds)
  • Images are optimized
  • Database queries are efficient
  • Connection pooling enabled
4

Monitoring

  • Error tracking configured (optional: Sentry)
  • Analytics setup (optional: Vercel Analytics)
  • Database backups scheduled
  • Uptime monitoring enabled

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

Build docs developers (and LLMs) love