730 lines
13 KiB
Markdown
730 lines
13 KiB
Markdown
# Estate Platform - Complete Setup Guide
|
|
|
|
## Table of Contents
|
|
1. [Quick Start](#quick-start)
|
|
2. [Prerequisites](#prerequisites)
|
|
3. [Local Development Setup](#local-development-setup)
|
|
4. [Docker Setup](#docker-setup)
|
|
5. [Redis Configuration](#redis-configuration)
|
|
6. [Database Setup](#database-setup)
|
|
7. [Authentication Setup](#authentication-setup)
|
|
8. [Testing the Application](#testing-the-application)
|
|
9. [Troubleshooting](#troubleshooting)
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
### Using Docker (Recommended)
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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](https://nodejs.org/))
|
|
- PostgreSQL 12+ ([Download](https://www.postgresql.org/download/))
|
|
- Redis 6+ ([Download](https://redis.io/download))
|
|
|
|
### Optional (for Docker)
|
|
- Docker ([Download](https://www.docker.com/products/docker-desktop))
|
|
- 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
|
|
|
|
```bash
|
|
# Verify installation
|
|
node --version # Should be v18+
|
|
npm --version # Should be v9+
|
|
```
|
|
|
|
### 2. Clone Repository
|
|
|
|
```bash
|
|
git clone <repo-url>
|
|
cd estate-platform
|
|
```
|
|
|
|
### 3. Install Dependencies
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
### 4. Configure Environment Variables
|
|
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# macOS
|
|
brew install docker
|
|
|
|
# Linux (Ubuntu)
|
|
sudo apt-get install docker.io docker-compose
|
|
|
|
# Verify installation
|
|
docker --version
|
|
docker-compose --version
|
|
```
|
|
|
|
### 2. Configure Environment
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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`:
|
|
|
|
```yaml
|
|
redis:
|
|
image: redis:7-alpine
|
|
ports:
|
|
- "6379:6379"
|
|
environment:
|
|
REDIS_PASSWORD: redis_password
|
|
volumes:
|
|
- redis_data:/data
|
|
```
|
|
|
|
### Local Redis Setup
|
|
|
|
#### macOS
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Using Windows Subsystem for Linux (WSL2)
|
|
# OR use Docker for Windows
|
|
docker run -d -p 6379:6379 redis:7-alpine
|
|
```
|
|
|
|
### Verify Redis Connection
|
|
|
|
```bash
|
|
# 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`:
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Install PostgreSQL
|
|
brew install postgresql@15
|
|
|
|
# Start PostgreSQL
|
|
brew services start postgresql@15
|
|
|
|
# Verify installation
|
|
psql --version
|
|
```
|
|
|
|
#### Linux (Ubuntu/Debian)
|
|
|
|
```bash
|
|
# Install PostgreSQL
|
|
sudo apt-get update
|
|
sudo apt-get install postgresql postgresql-contrib
|
|
|
|
# Start service
|
|
sudo systemctl start postgresql
|
|
|
|
# Verify
|
|
psql --version
|
|
```
|
|
|
|
### Create Database
|
|
|
|
```bash
|
|
# Connect to PostgreSQL
|
|
psql -U postgres
|
|
|
|
# Create database
|
|
CREATE DATABASE estate_platform;
|
|
|
|
# Exit
|
|
\q
|
|
```
|
|
|
|
### Run Migrations
|
|
|
|
```bash
|
|
# Generate Prisma client
|
|
npm run db:generate
|
|
|
|
# Run migrations
|
|
npm run db:migrate
|
|
|
|
# Seed database (optional)
|
|
npm run db:seed
|
|
```
|
|
|
|
### Database Commands
|
|
|
|
```bash
|
|
# 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](https://console.cloud.google.com/)
|
|
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](https://github.com/settings/developers)
|
|
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](https://developers.facebook.com/)
|
|
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](https://discord.com/developers/applications)
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
redis-cli
|
|
INFO stats
|
|
```
|
|
|
|
2. **Check Database**:
|
|
- Monitor slow queries
|
|
- Check indexes are created
|
|
|
|
3. **Check Resources**:
|
|
```bash
|
|
# Docker
|
|
docker stats
|
|
|
|
# Local
|
|
top # macOS/Linux
|
|
```
|
|
|
|
4. **Clear Cache**:
|
|
```bash
|
|
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**:
|
|
```bash
|
|
docker-compose down
|
|
```
|
|
|
|
**Remove all data** (fresh start):
|
|
```bash
|
|
docker-compose down -v
|
|
```
|
|
|
|
**Rebuild containers**:
|
|
```bash
|
|
docker-compose up -d --build
|
|
```
|
|
|
|
**View logs**:
|
|
```bash
|
|
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](https://nextjs.org/docs)
|
|
- [BetterAuth Documentation](https://better-auth.com)
|
|
- [Prisma Documentation](https://www.prisma.io/docs)
|
|
- [Redis Documentation](https://redis.io/documentation)
|
|
- [PostgreSQL Documentation](https://www.postgresql.org/docs)
|
|
|
|
For issues, check the [REDIS_SETUP.md](./REDIS_SETUP.md) for additional Redis-specific guidance.
|