Self-Hosted Installation

Overview

This guide covers deploying Home Manager on your own infrastructure. You’ll learn how to set up the database, configure authentication, and deploy the application.

Self-hosting requires technical knowledge of Node.js, PostgreSQL, and environment configuration. If you’re looking for a quick start without infrastructure setup, consider using a managed hosting service.

Prerequisites

Node.js

Version 20.x or higher required

PostgreSQL

Version 14 or higher (local or cloud-hosted)

Clerk Account

Free account for authentication service

Git

For cloning the repository

Installation Methods

Choose your preferred deployment method:

Docker
Vercel
Local Development
Custom Server

Recommended for production deployments

Step 1: Clone the Repository

Clone from GitHub

git clone https://github.com/Alexander-Malpica/home-manager-app.git
cd home-manager-app

Install Dependencies

Home Manager uses npm for package management:

npm install

This installs all required dependencies from package.json:

Next.js 15.3.2
React 19
Prisma 6.8.2
Clerk authentication
Material-UI 7.1.0
And more…

The postinstall script automatically runs prisma generate after installation.

Step 2: Set Up PostgreSQL Database

Option A: Local PostgreSQL

Install PostgreSQL

Install PostgreSQL 14+ on your system:

Ubuntu/Debian

sudo apt update
sudo apt install postgresql postgresql-contrib

macOS (Homebrew)

brew install postgresql@14
brew services start postgresql@14

Create Database

sudo -u postgres psql

CREATE DATABASE home_manager;
CREATE USER home_manager_user WITH ENCRYPTED PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE home_manager TO home_manager_user;
\q

Get Connection String

Your DATABASE_URL will be:

postgresql://home_manager_user:your_secure_password@localhost:5432/home_manager

Option B: Cloud PostgreSQL

Use a managed PostgreSQL service:

Supabase

Free tier available with generous limits

Neon

Serverless Postgres with instant scaling

Railway

Simple deployment with built-in PostgreSQL

Each service provides a connection string in the format:

postgresql://user:password@host:port/database?sslmode=require

Step 3: Configure Clerk Authentication

Create Clerk Account

Visit clerk.com and sign up
Create a new application
Choose authentication methods (Email, Google, GitHub, etc.)

Get API Keys

From your Clerk dashboard, navigate to API Keys and copy:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY (starts with pk_test_... or pk_live_...)
CLERK_SECRET_KEY (starts with sk_test_... or sk_live_...)

Configure Allowed Domains

In Clerk dashboard, add your application domains:

For local development: http://localhost:3000
For production: https://yourdomain.com

Set Redirect URLs

Configure these redirect URLs in Clerk:

Sign-in redirect: /dashboard
Sign-up redirect: /dashboard
Sign-out redirect: /

Clerk provides the authentication UI components used in src/app/page.tsx and handles all user management, password resets, and security.

Step 4: Environment Configuration

Create a .env.local file in the project root:

.env.local

# Database Connection
DATABASE_URL="postgresql://user:password@host:port/database"

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."
CLERK_SECRET_KEY="sk_test_..."

# Optional: Clerk Frontend API (usually auto-detected)
NEXT_PUBLIC_CLERK_SIGN_IN_URL="/"
NEXT_PUBLIC_CLERK_SIGN_UP_URL="/"
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL="/dashboard"
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL="/dashboard"

Never commit .env.local to version control. The .gitignore file already excludes .env* files.

Environment Variables Reference

Variable	Required	Description
`DATABASE_URL`	Yes	PostgreSQL connection string
`CLERK_SECRET_KEY`	Yes	Server-side Clerk authentication key
`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`	Yes	Client-side Clerk publishable key
`NEXT_PUBLIC_CLERK_SIGN_IN_URL`	No	Custom sign-in page path (default: `/`)
`NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL`	No	Redirect after sign-in (default: `/dashboard`)

Step 5: Initialize Database Schema

Home Manager uses Prisma ORM for database management:

Generate Prisma Client

npx prisma generate

This generates the Prisma client from prisma/schema.prisma.

Push Database Schema

npx prisma db push

This creates all required tables:

Household
HouseholdMember
ChoresItem
BillsItem
ShoppingItem
MaintenanceItem
Notification
AuditLog

Verify Database (Optional)

Use Prisma Studio to browse your database:

npx prisma studio

Opens at http://localhost:5555

For production, consider using prisma migrate deploy instead of db push to maintain migration history.

Step 6: Build and Deploy

Local Development

npm run dev

The application starts at http://localhost:3000 with Turbopack for fast hot-reloading.

Production Build

Build the Application

npm run build

This:

Runs prisma generate
Compiles TypeScript
Optimizes React components
Generates static pages
Creates production bundles

Start Production Server

npm start

Serves the optimized build on port 3000.

Deploy to Vercel

Install Vercel CLI

npm install -g vercel

Deploy

vercel

Follow the prompts to link your project.

Configure Environment Variables

In Vercel dashboard, add your environment variables:

DATABASE_URL
CLERK_SECRET_KEY
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY

Deploy to Production

vercel --prod

Vercel automatically detects Next.js and configures build settings. No additional configuration needed.

Deploy with Docker

Create a Dockerfile:

Dockerfile

FROM node:20-alpine AS base

# Install dependencies
FROM base AS deps
RUN apk add --no-cache libc6-compat openssl
WORKDIR /app

COPY package*.json ./
RUN npm ci

# Build application
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

ENV NEXT_TELEMETRY_DISABLED=1

RUN npx prisma generate
RUN npm run build

# Production image
FROM base 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 --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
COPY --from=builder /app/node_modules/.prisma ./node_modules/.prisma

USER nextjs

EXPOSE 3000

ENV PORT=3000
ENV HOSTNAME="0.0.0.0"

CMD ["node", "server.js"]

Build and run:

docker build -t home-manager .
docker run -p 3000:3000 \
  -e DATABASE_URL="postgresql://..." \
  -e CLERK_SECRET_KEY="sk_..." \
  -e NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_..." \
  home-manager

Deploy to Custom Server

For VPS or dedicated servers:

Transfer Files

scp -r home-manager-app user@your-server:/var/www/

Install Node.js and PostgreSQL

On your server:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs postgresql

Configure Environment

Create .env.local on the server with your configuration

Install and Build

cd /var/www/home-manager-app
npm install
npx prisma db push
npm run build

Use Process Manager

Install PM2 for process management:

npm install -g pm2
pm2 start npm --name "home-manager" -- start
pm2 startup
pm2 save

Configure Reverse Proxy

Use Nginx or Apache to proxy to port 3000:

/etc/nginx/sites-available/home-manager

server {
    listen 80;
    server_name yourdomain.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;
    }
}

Enable SSL with Certbot

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com

Step 7: Post-Deployment Configuration

Configure Clerk for Production

Update Clerk dashboard with production domain
Switch from test keys to live keys
Configure production sign-in/sign-up URLs

Database Backup Strategy

Automated Backups

# Cron job for daily backups
0 2 * * * pg_dump -U home_manager_user home_manager > /backups/home_manager_$(date +\%Y\%m\%d).sql

Retention Policy

Keep 30 daily, 12 monthly backups

Monitoring and Logging

Consider implementing:

Application monitoring (e.g., Sentry, LogRocket)
Database monitoring (connection pools, slow queries)
Server monitoring (CPU, memory, disk usage)

Troubleshooting

Database connection fails

Symptoms: PrismaClientInitializationErrorSolutions:

Verify DATABASE_URL format is correct
Check PostgreSQL is running: sudo systemctl status postgresql
Verify user has correct permissions: GRANT ALL PRIVILEGES ON DATABASE home_manager TO home_manager_user;
For cloud databases, ensure SSL mode is set: ?sslmode=require

Clerk authentication not working

Symptoms: Redirect loops, 401 errorsSolutions:

Verify all Clerk environment variables are set correctly
Check that domain is added to Clerk allowed origins
Ensure you’re using the correct keys (test vs. live)
Clear browser cookies and try again
Review middleware configuration in src/middleware.ts

Build fails with Prisma errors

Symptoms: Cannot find module '@prisma/client'Solutions:

Run npx prisma generate before building
Delete node_modules and reinstall: rm -rf node_modules && npm install
Ensure DATABASE_URL is set during build (required for Prisma)

Port 3000 already in use

Solutions:

# Find process using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or use a different port
PORT=3001 npm start

Security Best Practices

Follow these security guidelines for production deployments:

Use strong database passwords: Generate random 32+ character passwords
Enable SSL/TLS: Always use HTTPS in production
Restrict database access: Only allow connections from application server IP
Regular updates: Keep dependencies up to date with npm audit
Environment isolation: Never reuse credentials between staging and production
Backup encryption: Encrypt database backups at rest
Rate limiting: Implement rate limiting on API routes (consider Clerk rate limits)

Performance Optimization

Database Optimization

-- Add indexes for better query performance
CREATE INDEX idx_chores_household ON "ChoresItem"("householdId");
CREATE INDEX idx_bills_household ON "BillsItem"("householdId");
CREATE INDEX idx_shopping_household ON "ShoppingItem"("householdId");
CREATE INDEX idx_maintenance_household ON "MaintenanceItem"("householdId");
CREATE INDEX idx_household_members_user ON "HouseholdMember"("userId");

Next.js Optimization

The application is already optimized with:

Server-side rendering for initial page loads
API routes for backend logic
Turbopack for fast development builds
Material-UI emotion cache for CSS-in-JS performance

Maintenance Tasks

Regular Maintenance Checklist

Weekly: Review application logs for errors
Weekly: Check database size and growth
Monthly: Update dependencies (npm update)
Monthly: Review Clerk usage and limits
Quarterly: Database vacuum and analyze
Quarterly: Review and rotate API keys

Database Maintenance

-- Vacuum and analyze (PostgreSQL)
VACUUM ANALYZE;

-- Check database size
SELECT pg_size_pretty(pg_database_size('home_manager'));

Upgrading

To upgrade to a new version:

Backup Database

pg_dump -U home_manager_user home_manager > backup_before_upgrade.sql

Pull Latest Changes

git pull origin main

Update Dependencies

npm install

Run Migrations

npx prisma migrate deploy

Rebuild and Restart

npm run build
pm2 restart home-manager

Support and Resources

GitHub Repository

Source code, issues, and contributions

Clerk Documentation

Authentication setup and configuration

Prisma Documentation

Database management and queries

Next.js Documentation

Framework documentation and guides

Next Steps

After successful installation:

Test All Features

Create test households, chores, and bills to verify functionality

Configure Backups

Set up automated database backups

Set Up Monitoring

Implement error tracking and performance monitoring

Train Users

Share the Quick Start Guide with your users

Get Started

Core Features

User Guide

Deployment

​Overview

​Prerequisites

Node.js

PostgreSQL

Clerk Account

Git

​Installation Methods

​Step 1: Clone the Repository

​Step 2: Set Up PostgreSQL Database

​Option A: Local PostgreSQL

​Option B: Cloud PostgreSQL

Supabase

Neon

Railway

​Step 3: Configure Clerk Authentication

​Step 4: Environment Configuration

​Environment Variables Reference

​Step 5: Initialize Database Schema

​Step 6: Build and Deploy

​Local Development

​Production Build

​Deploy to Vercel

​Deploy with Docker

​Deploy to Custom Server

​Step 7: Post-Deployment Configuration

​Configure Clerk for Production

​Database Backup Strategy

​Monitoring and Logging

​Troubleshooting

​Security Best Practices

​Performance Optimization

​Database Optimization

​Next.js Optimization

​Maintenance Tasks

​Regular Maintenance Checklist

​Database Maintenance

​Upgrading

​Support and Resources

GitHub Repository

Clerk Documentation

Prisma Documentation

Next.js Documentation

​Next Steps

Build docs developers (and LLMs) love

Overview

Prerequisites

Installation Methods

Step 1: Clone the Repository

Step 2: Set Up PostgreSQL Database

Option A: Local PostgreSQL

Option B: Cloud PostgreSQL

Step 3: Configure Clerk Authentication

Step 4: Environment Configuration

Environment Variables Reference

Step 5: Initialize Database Schema

Step 6: Build and Deploy

Local Development

Production Build

Deploy to Vercel

Deploy with Docker

Deploy to Custom Server

Step 7: Post-Deployment Configuration

Configure Clerk for Production

Database Backup Strategy

Monitoring and Logging

Troubleshooting

Security Best Practices

Performance Optimization

Database Optimization

Next.js Optimization

Maintenance Tasks

Regular Maintenance Checklist

Database Maintenance

Upgrading

Support and Resources

Next Steps