yourwillyourwish/docs/COMPLETE_SETUP_GUIDE.md

Estate Platform - Complete Setup Guide

Table of Contents

1. Quick Start
2. Prerequisites
3. Local Development Setup
4. Docker Setup
5. Redis Configuration
6. Database Setup
7. Authentication Setup
8. Testing the Application
9. Troubleshooting

---

Quick Start

Using Docker (Recommended)

# 1. Clone the repository
git clone <repo-url>
cd estate-platform

# 2. Copy environment file
cp .env.example .env.local

# 3. Start all services (includes Redis)
docker-compose up -d

# 4. Run database migrations
docker-compose exec web npm run db:migrate

# 5. Seed the database (optional)
docker-compose exec web npm run db:seed

# 6. Access the application
open http://localhost:3000

Local Development

# 1. Install dependencies
npm install

# 2. Start Redis locally (macOS)
redis-server

# 3. Setup database
npm run db:migrate
npm run db:seed

# 4. Run development server
npm run dev

# 5. Open browser
open http://localhost:3001

---

Prerequisites

Required

• Node.js 18+ (Download)
• PostgreSQL 12+ (Download)
• Redis 6+ (Download)

Optional (for Docker)

• Docker (Download)
• Docker Compose (included with Docker Desktop)

For OAuth Providers (optional)

• Google OAuth credentials
• GitHub OAuth credentials
• Facebook OAuth credentials
• Discord OAuth credentials

---

Local Development Setup

1. Install Node.js

# Verify installation
node --version  # Should be v18+
npm --version   # Should be v9+

2. Clone Repository

git clone <repo-url>
cd estate-platform

3. Install Dependencies

npm install

4. Configure Environment Variables

# Copy example environment file
cp .env.example .env.local

# Edit with your values
nano .env.local  # or use your preferred editor

Important variables to set:

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/estate_platform"
REDIS_URL="redis://localhost:6379"
APP_BASE_URL="http://localhost:3001"
BETTER_AUTH_SECRET="your-random-secret-key"

5. Setup PostgreSQL Database

# Create database (if not exists)
createdb estate_platform

# Run migrations
npm run db:migrate

# Optional: Seed with sample data
npm run db:seed

6. Start Redis

# macOS (using Homebrew)
redis-server

# Linux (systemd)
sudo systemctl start redis-server

# Verify Redis is running
redis-cli ping  # Should output "PONG"

7. Start Development Server

npm run dev

# Server runs at http://localhost:3001

8. Verify Setup

Open your browser and navigate to:

• Frontend: http://localhost:3001
• Admin Setup: http://localhost:3001/admin/setup
• API Health: http://localhost:3001/api/health (if available)

---

Docker Setup

1. Install Docker

# macOS
brew install docker

# Linux (Ubuntu)
sudo apt-get install docker.io docker-compose

# Verify installation
docker --version
docker-compose --version

2. Configure Environment

# Copy and edit environment
cp .env.example .env.local

# For Docker, use:
REDIS_URL="redis://:redis_password@redis:6379"
DATABASE_URL="postgresql://postgres:postgres@postgres:5432/estate_platform"

3. Start Services

# Start all services in background
docker-compose up -d

# View logs
docker-compose logs -f

# View specific service logs
docker-compose logs -f web    # Next.js app
docker-compose logs -f redis  # Redis
docker-compose logs -f postgres  # Database

4. Initialize Database

# Run migrations inside Docker
docker-compose exec web npm run db:migrate

# Seed with sample data
docker-compose exec web npm run db:seed

5. Access Application

• Frontend: http://localhost:3000
• Admin Setup: http://localhost:3000/admin/setup

6. Stop Services

# Stop containers
docker-compose down

# Stop and remove volumes (WARNING: deletes data!)
docker-compose down -v

---

Redis Configuration

Docker Setup (Recommended)

Redis is automatically configured in docker-compose.yml:

redis:
  image: redis:7-alpine
  ports:
    - "6379:6379"
  environment:
    REDIS_PASSWORD: redis_password
  volumes:
    - redis_data:/data

Local Redis Setup

macOS

# Install with Homebrew
brew install redis

# Start Redis
redis-server

# Start as service (starts on boot)
brew services start redis

# Stop service
brew services stop redis

# Verify connection
redis-cli ping  # Should output "PONG"

Linux (Ubuntu/Debian)

# Install Redis
sudo apt-get update
sudo apt-get install redis-server

# Start service
sudo systemctl start redis-server

# Enable on boot
sudo systemctl enable redis-server

# Check status
sudo systemctl status redis-server

# Verify connection
redis-cli ping  # Should output "PONG"

Windows

# Using Windows Subsystem for Linux (WSL2)
# OR use Docker for Windows
docker run -d -p 6379:6379 redis:7-alpine

Verify Redis Connection

# Connect to Redis CLI
redis-cli

# Test commands
ping              # Returns "PONG"
set key value     # Set a key
get key           # Get the value
del key           # Delete the key
FLUSHALL          # Clear all data (be careful!)
exit              # Exit CLI

Configure Environment Variables

In .env.local:

# Local development
REDIS_URL="redis://localhost:6379"

# Docker setup
REDIS_URL="redis://:redis_password@redis:6379"

# With password (production)
REDIS_URL="redis://:your_strong_password@localhost:6379"

---

Database Setup

Using Docker (Easiest)

# Database runs automatically with docker-compose
docker-compose up -d postgres

# Run migrations
docker-compose exec web npm run db:migrate

# Seed data
docker-compose exec web npm run db:seed

# Access database
docker-compose exec postgres psql -U postgres -d estate_platform

Local PostgreSQL Setup

macOS

# Install PostgreSQL
brew install postgresql@15

# Start PostgreSQL
brew services start postgresql@15

# Verify installation
psql --version

Linux (Ubuntu/Debian)

# Install PostgreSQL
sudo apt-get update
sudo apt-get install postgresql postgresql-contrib

# Start service
sudo systemctl start postgresql

# Verify
psql --version

Create Database

# Connect to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE estate_platform;

# Exit
\q

Run Migrations

# Generate Prisma client
npm run db:generate

# Run migrations
npm run db:migrate

# Seed database (optional)
npm run db:seed

Database Commands

# Generate Prisma client after schema changes
npm run db:migrate

# Create new migration (if using manual SQL)
npm run db:migrate

# Reset database (WARNING: deletes all data!)
npx prisma migrate reset

# View database
npx prisma studio

---

Authentication Setup

BetterAuth Configuration

BetterAuth is configured in lib/auth.ts. Sessions are automatically cached with Redis.

Add OAuth Providers

1. Navigate to Admin Setup

   • URL: http://localhost:3001/admin/setup
   • Login as admin user

2. Configure OAuth Providers

   • Click each provider (Google, GitHub, Facebook, Discord)
   • Add Client ID and Client Secret
   • Save configuration

3. Get Provider Credentials

Google OAuth

1. Go to Google Cloud Console
2. Create new project
3. Enable Google+ API
4. Create OAuth 2.0 credentials (Web application)
5. Add authorized redirect URIs:
   • http://localhost:3001/auth/google/callback
   • https://yourdomain.com/auth/google/callback
6. Copy Client ID and Client Secret to admin setup

GitHub OAuth

1. Go to GitHub Settings
2. Click "New OAuth App"
3. Fill in application details:
   • Authorization callback URL: http://localhost:3001/auth/github/callback
4. Copy Client ID and Client Secret

Facebook OAuth

1. Go to Facebook Developers
2. Create new app
3. Add Facebook Login product
4. Set Valid OAuth Redirect URIs:
   • http://localhost:3001/auth/facebook/callback
5. Copy App ID and App Secret

Discord OAuth

1. Go to Discord Developer Portal
2. Create new application
3. Go to OAuth2 settings
4. Add redirect URI:
   • http://localhost:3001/auth/discord/callback
5. Copy Client ID and Client Secret

Session Management

Sessions are automatically cached with Redis:

• Cache duration: 7 days
• Auto-expiry: TTL automatically managed
• User data cache: 1 hour (reduces database queries)

---

Testing the Application

Test User Creation

1. Go to /signup
2. Fill in user details:
   • First Name: "John"
   • Last Name: "Doe"
   • Email: "john@example.com"
   • Password: "SecurePassword123"
3. Click Sign Up

Test OAuth Login

1. Go to /signin
2. Click any OAuth provider button
3. Authenticate with provider credentials
4. Should redirect to dashboard

Test Admin Setup

1. Login as admin
2. Navigate to /admin/setup
3. Configure OAuth providers
4. Save settings (cached with Redis)
5. Verify settings persist

Test Redis Caching

# Connect to Redis
redis-cli

# Monitor cache operations
MONITOR

# In another terminal, make API calls
curl http://localhost:3001/api/admin/setup

# You should see Redis commands in monitor

Test Database

# View Prisma studio
npm run db:studio

# Or connect directly
psql -U postgres -d estate_platform

# Query users
SELECT * FROM "User";

# Query sessions
SELECT * FROM "Session";

---

Troubleshooting

Redis Connection Issues

Error: Error: connect ECONNREFUSED 127.0.0.1:6379

Solution:

# Check if Redis is running
redis-cli ping

# Start Redis
redis-server

# Or check Docker
docker-compose logs redis
docker-compose restart redis

Database Connection Issues

Error: Error: connect ECONNREFUSED localhost:5432

Solution:

# Check PostgreSQL status
psql -U postgres -c "SELECT version();"

# Start PostgreSQL
brew services start postgresql@15  # macOS
sudo systemctl start postgresql     # Linux

# Check Docker
docker-compose logs postgres
docker-compose restart postgres

Port Already in Use

Error: Port 3001 is already in use

Solution:

# Kill process using port
lsof -i :3001
kill -9 <PID>

# Or use different port
npm run dev -- -p 3002

Authentication Issues

Issue: Cannot login or OAuth not working

Solution:

1. Check OAuth credentials in admin setup
2. Verify OAuth callback URLs match provider settings
3. Check browser cookies: Settings > Cookies > estate-platform
4. Clear cache: Ctrl+Shift+Delete (Chrome)
5. Check console for errors: F12 > Console

Admin Setup Page Blank

Issue: /admin/setup page shows nothing

Solution:

1. Ensure logged in as admin
2. Check Redis connection: redis-cli ping
3. Check API response: curl http://localhost:3001/api/admin/setup
4. Check browser console for errors
5. Restart application

Slow Performance

Issue: Application feels slow

Solution:

1. Check Redis:

   redis-cli
   INFO stats
   

2. Check Database:

   • Monitor slow queries
   • Check indexes are created

3. Check Resources:

   # Docker
   docker stats
   
   # Local
   top  # macOS/Linux
   

4. Clear Cache:

   redis-cli FLUSHALL  # WARNING: clears all cache!
   

Can't Access Admin Setup

Issue: /admin/setup returns 401 Unauthorized

Solution:

1. Check user role is "ADMIN" in database
2. Verify session/auth token exists
3. Check JWT secret in .env.local
4. Login again to refresh session

Docker Issues

Stop all containers:

docker-compose down

Remove all data (fresh start):

docker-compose down -v

Rebuild containers:

docker-compose up -d --build

View logs:

docker-compose logs -f [service]  # web, redis, postgres

---

Performance Optimization Tips

1. Enable Redis Caching

   • All API responses are automatically cached
   • Reduces database queries by 50-70%

2. Optimize Database Indexes

   • Check prisma/schema.prisma for @@index
   • Add indexes for frequently queried fields

3. Use CDN for Static Assets

   • Configure Cloudflare or similar
   • Serve images and CSS globally

4. Monitor with Tools

   • Use npm run db:studio for queries
   • Use redis-cli MONITOR for cache hits
   • Use browser DevTools for performance

5. Enable Compression

   • Gzip enabled by default in Next.js
   • Verify with: curl -I http://localhost:3001 | grep encoding

---

Next Steps

1. Configure OAuth providers for your environment
2. Setup email service for notifications
3. Configure Stripe for payments (if needed)
4. Deploy to production environment
5. Setup monitoring and logging
6. Configure backups for database and Redis

---

Support & Resources

• Next.js Documentation
• BetterAuth Documentation
• Prisma Documentation
• Redis Documentation
• PostgreSQL Documentation

For issues, check the REDIS_SETUP.md for additional Redis-specific guidance.