Initial commit
This commit is contained in:
Developer
729
docs/COMPLETE_SETUP_GUIDE.md
Normal file
729
docs/COMPLETE_SETUP_GUIDE.md
Normal file
@@ -0,0 +1,729 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user