refactor: move deployment docs to docs/deployment/ directory

2026-03-31 21:49:12 -07:00
parent 0e1046fcb5
commit 9511eed477
2 changed files with 643 additions and 0 deletions
@@ -0,0 +1,273 @@
+# EuchreCamp CasaOS Deployment Guide
+
+This guide explains how to deploy EuchreCamp on your CasaOS server.
+
+## Prerequisites
+
+1. **CasaOS** installed on your server
+2. **Docker** and **Docker Compose** available in CasaOS
+3. **Port 3000** available for the web interface
+4. **Port 5432** available for PostgreSQL (or use external database)
+
+## Prerequisites
+
+**External PostgreSQL Database Required**
+- PostgreSQL 15 or higher
+- Database name: `euchre_camp`
+- User: `euchre_camp`
+- Privileges: ALL on database `euchre_camp`
+
+## Quick Start
+
+### Option 1: Using CasaOS App Store (Recommended)
+
+1. **Set up PostgreSQL database first** (see below)
+2. Open CasaOS Dashboard
+3. Go to **App Store** → **Custom App**
+4. Click **Install** and configure the following:
+
+   **Basic Settings:**
+   - App Name: `EuchreCamp`
+   - Image: `euchre-camp:latest` (build locally first)
+   - Port: `3000`
+
+   **Environment Variables:**
+   ```
+   DATABASE_URL=postgresql://euchre_camp:password@your-postgres-host:5432/euchre_camp
+   DATABASE_SHADOW_URL=postgresql://euchre_camp:password@your-postgres-host:5432/euchre_camp_shadow
+   BETTER_AUTH_SECRET=your-secret-key-here
+   BETTER_AUTH_URL=http://your-casaos-ip:3000
+   TRUSTED_ORIGINS=http://your-casaos-ip:3000
+   ```
+
+5. Click **Install**
+
+### Option 2: Using Docker Compose
+
+1. **Set up PostgreSQL database first** (see below)
+2. **Build the Docker image:**
+   ```bash
+   docker-compose -f docker-compose.casaos.yml build
+   ```
+
+3. **Start the application:**
+   ```bash
+   docker-compose -f docker-compose.casaos.yml up -d
+   ```
+
+4. **Check logs:**
+   ```bash
+   docker-compose -f docker-compose.casaos.yml logs -f
+   ```
+
+## PostgreSQL Database Setup
+
+### Option A: External PostgreSQL Server
+
+Connect to your PostgreSQL server and run:
+
+```sql
+-- Create database
+CREATE DATABASE euchre_camp;
+
+-- Create user
+CREATE USER euchre_camp WITH PASSWORD 'your-strong-password';
+
+-- Grant privileges
+GRANT ALL PRIVILEGES ON DATABASE euchre_camp TO euchre_camp;
+
+-- Connect to database
+\c euchre_camp
+
+-- Grant schema privileges
+GRANT ALL ON SCHEMA public TO euchre_camp;
+```
+
+### Option B: CasaOS PostgreSQL Container
+
+If you want to run PostgreSQL in CasaOS:
+
+1. Install PostgreSQL from CasaOS App Store
+2. Configure it with:
+   - Database: `euchre_camp`
+   - User: `euchre_camp`
+   - Password: `your-strong-password`
+3. Use the connection string in your EuchreCamp configuration:
+   ```
+   DATABASE_URL=postgresql://euchre_camp:your-strong-password@192.168.1.100:5432/euchre_camp
+   ```
+   (Replace `192.168.1.100` with your CasaOS IP)
+
+## Configuration
+
+### Required Environment Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `DATABASE_URL` | PostgreSQL connection string (REQUIRED) | `postgresql://euchre_camp:pass@host:5432/euchre_camp` |
+| `BETTER_AUTH_SECRET` | Secret key for session encryption (generate with `openssl rand -base64 32`) | `your-generated-secret` |
+| `BETTER_AUTH_URL` | Public URL of your application | `http://192.168.1.100:3000` |
+| `TRUSTED_ORIGINS` | Comma-separated list of trusted origins | `http://192.168.1.100:3000` |
+
+### Optional Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `DATABASE_SHADOW_URL` | Shadow database for migrations | Same as DATABASE_URL with `_shadow` suffix |
+
+## Database Management
+
+### First-Time Setup
+
+1. **Create the database and user** (see PostgreSQL Setup above)
+2. **Run database migrations:**
+   ```bash
+   docker exec -it euchre-camp npx prisma migrate deploy
+   ```
+3. **Create admin user:**
+   ```bash
+   docker exec -it euchre-camp node scripts/create-admin-via-api.js
+   ```
+
+### Accessing the Database
+
+```bash
+# Connect to external PostgreSQL server
+psql -h your-postgres-host -U euchre_camp -d euchre_camp
+
+# List tables
+\dt
+
+# Exit
+\q
+```
+
+### Backing Up Data
+
+```bash
+# Backup PostgreSQL data (run on your PostgreSQL server)
+pg_dump -h your-postgres-host -U euchre_camp euchre_camp > backup.sql
+
+# Backup uploaded files
+tar -czf euchre_camp_files.tar.gz /var/lib/docker/volumes/euchre_camp_app_data
+```
+
+## Security Considerations
+
+### Change Default Passwords
+
+1. **PostgreSQL Password:**
+   - Edit `docker-compose.casaos.yml` or set via CasaOS environment variables
+   - Update `POSTGRES_PASSWORD` to a strong password
+
+2. **Better Auth Secret:**
+   ```bash
+   openssl rand -base64 32
+   ```
+   - Use this value for `BETTER_AUTH_SECRET`
+
+### HTTPS Setup
+
+For production use with HTTPS:
+
+1. **Option A: CasaOS Reverse Proxy**
+   - Configure CasaOS to use HTTPS
+   - Update `BETTER_AUTH_URL` to `https://your-domain.com`
+
+2. **Option B: External Reverse Proxy (Nginx, Traefik)**
+   - Configure your reverse proxy
+   - Update `TRUSTED_ORIGINS` to include your domain
+
+### Firewall Rules
+
+Ensure only necessary ports are exposed:
+- **Port 3000**: Web interface (HTTP/HTTPS)
+- **Port 5432**: PostgreSQL (only if external access needed)
+
+## Troubleshooting
+
+### Database Connection Issues
+
+```bash
+# Check PostgreSQL logs
+docker logs euchre-camp-postgres
+
+# Check if PostgreSQL is healthy
+docker exec euchre-camp-postgres pg_isready -U euchre -d euchre_camp
+```
+
+### Application Not Starting
+
+```bash
+# Check application logs
+docker logs euchre-camp
+
+# Check if Prisma migrations are applied
+docker exec euchre-camp npx prisma migrate status
+```
+
+### Permission Issues
+
+If you see permission errors:
+```bash
+# Fix volume permissions
+docker exec euchre-camp chown -R euchre:euchre /app/public/uploads
+```
+
+## Performance Tuning
+
+### PostgreSQL Optimization
+
+Add to `docker-compose.casaos.yml` under `postgres` service:
+```yaml
+environment:
+  - POSTGRES_SHARED_BUFFERS=256MB
+  - POSTGRES_WORK_MEM=16MB
+```
+
+### Application Optimization
+
+The Dockerfile is already optimized with:
+- Multi-stage build (smaller image size)
+- Non-root user for security
+- Health checks
+- Production-ready settings
+
+## Updating
+
+To update EuchreCamp:
+
+```bash
+# Pull latest changes
+git pull origin main
+
+# Rebuild and restart
+docker-compose -f docker-compose.casaos.yml down
+docker-compose -f docker-compose.casaos.yml build --no-cache
+docker-compose -f docker-compose.casaos.yml up -d
+```
+
+## Monitoring
+
+### View Logs
+```bash
+docker-compose -f docker-compose.casaos.yml logs -f
+```
+
+### Check Container Status
+```bash
+docker ps | grep euchre
+```
+
+### Resource Usage
+```bash
+docker stats euchre-camp euchre-camp-postgres
+```
+
+## Support
+
+For issues or questions:
+- Check the application logs first
+- Verify environment variables are set correctly
+- Ensure PostgreSQL is running and accessible
+- Check CasaOS app logs for deployment issues
@@ -0,0 +1,370 @@
+# Docker Deployment Guide
+
+This guide covers how to run EuchreCamp using Docker and Docker Compose.
+
+## Prerequisites
+
+- Docker Engine 20.10+
+- Docker Compose v2.0+
+- Make (optional, for using Makefile commands)
+
+## Quick Start
+
+### 1. Environment Setup
+
+Create a `.env` file in the project root:
+
+```bash
+cp .env.example .env
+```
+
+Update the `.env` file with your configuration:
+
+```env
+# Database Configuration (PostgreSQL in Docker)
+DATABASE_PROVIDER=postgresql
+DATABASE_URL=postgresql://euchre:euchrepassword@postgres:5432/euchre_camp
+DATABASE_SHADOW_URL=postgresql://euchre:euchrepassword@postgres:5432/euchre_camp_shadow
+
+# Better Auth (generate a secure secret for production)
+BETTER_AUTH_SECRET=your-secret-key-change-in-production
+BETTER_AUTH_URL=http://localhost:3000
+
+# Application
+NODE_ENV=production
+TRUSTED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
+```
+
+### 2. Build and Run
+
+#### Production Mode
+
+```bash
+# Build and start all services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Stop all services
+docker-compose down
+```
+
+#### Development Mode
+
+```bash
+# Use development override configuration
+docker-compose -f docker-compose.yml -f docker-compose.override.yml up -d
+
+# Or use the shorthand
+docker-compose --profile dev up -d
+```
+
+### 3. Access the Application
+
+- **Web Application**: http://localhost:3000
+- **PostgreSQL**: localhost:5432 (default) or 5433 in development
+
+## Service Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│                 EuchreCamp                  │
+├─────────────────────────────────────────────┤
+│                                             │
+│  ┌──────────────┐    ┌──────────────────┐  │
+│  │   Next.js    │◄───│   PostgreSQL     │  │
+│  │   App        │    │   Database       │  │
+│  │              │    │                  │  │
+│  │  Port: 3000  │    │  Port: 5432      │  │
+│  └──────────────┘    └──────────────────┘  │
+│                                             │
+└─────────────────────────────────────────────┘
+```
+
+## Service Details
+
+### App Service
+
+- **Image**: Multi-stage Next.js build
+- **Port**: 3000
+- **Environment**: Production or Development
+- **Volumes**: 
+  - `app_data`: Persistent storage for uploads
+
+### PostgreSQL Service
+
+- **Image**: postgres:15-alpine
+- **Port**: 5432 (production) / 5433 (development)
+- **Data Volume**: `postgres_data` (persistent)
+- **Health Check**: Uses `pg_isready`
+
+## Database Management
+
+### View Database Data
+
+```bash
+# Access PostgreSQL shell
+docker exec -it euchre-camp-postgres psql -U euchre -d euchre_camp
+
+# List tables
+\dt
+
+# Exit
+\q
+```
+
+### Backup Database
+
+```bash
+# Create backup
+docker exec euchre-camp-postgres pg_dump -U euchre euchre_camp > backup.sql
+
+# Restore backup
+docker exec -i euchre-camp-postgres psql -U euchre euchre_camp < backup.sql
+```
+
+### Reset Database
+
+```bash
+# Remove all data and restart
+docker-compose down -v
+docker-compose up -d
+```
+
+## Running Commands
+
+### Run Database Migrations
+
+```bash
+# Apply migrations
+docker-compose exec app npx prisma migrate deploy
+
+# Generate Prisma client
+docker-compose exec app npx prisma generate
+
+# Open Prisma Studio
+docker-compose exec app npx prisma studio
+```
+
+### Create Admin User
+
+```bash
+# Create admin user via script
+docker-compose exec app node scripts/create-admin-via-api.js
+```
+
+### Seed Database
+
+```bash
+# Run seed script
+docker-compose exec app node scripts/seed.js
+```
+
+## Development Workflow
+
+### Hot Reloading
+
+Development mode supports hot reloading:
+
+```bash
+# Start in development mode
+docker-compose -f docker-compose.yml -f docker-compose.override.yml up -d
+
+# View logs
+docker-compose logs -f app
+```
+
+### Modifying Code
+
+Changes to source code are automatically reflected due to volume mounting:
+
+```bash
+# Edit a file locally
+nano src/app/page.tsx
+
+# Next.js will automatically reload
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**1. Database Connection Failed**
+
+```bash
+# Check if PostgreSQL is running
+docker ps | grep postgres
+
+# Check logs
+docker logs euchre-camp-postgres
+
+# Restart services
+docker-compose restart postgres
+```
+
+**2. Port Already in Use**
+
+```bash
+# Check what's using port 3000
+lsof -i :3000
+
+# Change port in docker-compose.yml
+# ports:
+#   - "3001:3000"
+```
+
+**3. Permission Denied**
+
+```bash
+# Ensure scripts are executable
+chmod +x scripts/*.sh
+
+# Check volume permissions
+docker exec euchre-camp-app ls -la /app
+```
+
+**4. Migration Errors**
+
+```bash
+# Reset database
+docker-compose down -v
+docker-compose up -d
+
+# Apply migrations manually
+docker-compose exec app npx prisma migrate deploy
+```
+
+### View Logs
+
+```bash
+# All services
+docker-compose logs -f
+
+# Specific service
+docker-compose logs -f app
+docker-compose logs -f postgres
+```
+
+### Container Shell Access
+
+```bash
+# App container
+docker exec -it euchre-camp-app sh
+
+# PostgreSQL container
+docker exec -it euchre-camp-postgres sh
+```
+
+## Production Deployment
+
+### Environment Variables
+
+For production, ensure you set secure values:
+
+```env
+# Generate a secure secret
+BETTER_AUTH_SECRET=$(openssl rand -base64 32)
+
+# Use real domain
+BETTER_AUTH_URL=https://euchrecamp.example.com
+
+# Trusted origins
+TRUSTED_ORIGINS=https://euchrecamp.example.com,https://www.euchrecamp.example.com
+```
+
+### Security Considerations
+
+1. **Change default PostgreSQL password**:
+   ```env
+   POSTGRES_PASSWORD=your-secure-password
+   ```
+
+2. **Use SSL/TLS for database connections**:
+   ```env
+   DATABASE_URL=postgresql://euchre:password@postgres:5432/euchre_camp?sslmode=require
+   ```
+
+3. **Restrict network access**:
+   - Don't expose PostgreSQL port to public internet
+   - Use firewall rules to restrict access
+
+4. **Regular backups**:
+   - Schedule automated database backups
+   - Test restoration process
+
+### Docker Swarm / Kubernetes
+
+For production orchestration, consider:
+
+1. **Separate database service** - Use managed PostgreSQL (RDS, Cloud SQL)
+2. **Secrets management** - Use Docker secrets or Kubernetes Secrets
+3. **Health checks** - Configure proper health checks
+4. **Resource limits** - Set CPU and memory limits
+5. **Replicas** - Run multiple app instances for high availability
+
+## Makefile (Optional)
+
+Create a `Makefile` for convenient commands:
+
+```makefile
+.PHONY: up down logs build shell-migrate
+
+up:
+	docker-compose up -d
+
+down:
+	docker-compose down
+
+logs:
+	docker-compose logs -f
+
+build:
+	docker-compose build --no-cache
+
+shell-app:
+	docker exec -it euchre-camp-app sh
+
+shell-db:
+	docker exec -it euchre-camp-postgres psql -U euchre -d euchre_camp
+
+migrate:
+	docker-compose exec app npx prisma migrate deploy
+
+seed:
+	docker-compose exec app node scripts/seed.js
+```
+
+## Performance Tuning
+
+### PostgreSQL Configuration
+
+Edit `docker-compose.yml` to tune PostgreSQL:
+
+```yaml
+postgres:
+  # ... other config ...
+  command: >
+    postgres
+    -c max_connections=200
+    -c shared_buffers=256MB
+    -c effective_cache_size=1GB
+    -c maintenance_work_mem=64MB
+    -c checkpoint_completion_target=0.9
+    -c wal_buffers=16MB
+    -c default_statistics_target=100
+```
+
+### Next.js Optimization
+
+The Dockerfile uses multi-stage build for optimal size and performance:
+
+- **Builder stage**: Installs all dependencies and builds the app
+- **Runner stage**: Copies only the built artifacts and production dependencies
+
+## References
+
+- [Docker Compose Documentation](https://docs.docker.com/compose/)
+- [PostgreSQL Docker Image](https://hub.docker.com/_/postgres)
+- [Next.js Deployment](https://nextjs.org/docs/deployment)
+- [Prisma Deployment](https://www.prisma.io/docs/concepts/components/prisma-migrate/deployment)