chore: add CasaOS deployment configuration and documentation

2026-03-31 03:56:50 -07:00
parent f49d0f02d9
commit 4c432f0971
3 changed files with 299 additions and 2 deletions
@@ -39,10 +39,12 @@ prisma/prisma/dev.db*
 .git
 .gitignore

-# Docker
+# Docker (but allow CasaOS config)
 Dockerfile
-docker-compose*.yml
+docker-compose.yml
+docker-compose.override.yml
 .dockerignore
+!docker-compose.casaos.yml

 # Misc
 .DS_Store
@@ -0,0 +1,220 @@
+# 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)
+
+## Quick Start
+
+### Option 1: Using CasaOS App Store (Recommended)
+
+1. Open CasaOS Dashboard
+2. Go to **App Store** → **Custom App**
+3. Click **Install** and configure the following:
+
+   **Basic Settings:**
+   - App Name: `EuchreCamp`
+   - Image: `euchre-camp:latest` (build locally first)
+   - Port: `3000`
+
+   **Environment Variables:**
+   ```
+   BETTER_AUTH_SECRET=your-secret-key-here
+   BETTER_AUTH_URL=http://your-casaos-ip:3000
+   TRUSTED_ORIGINS=http://your-casaos-ip:3000
+   ```
+
+4. Click **Install**
+
+### Option 2: Using Docker Compose
+
+1. **Build the Docker image:**
+   ```bash
+   docker-compose -f docker-compose.casaos.yml build
+   ```
+
+2. **Start the application:**
+   ```bash
+   docker-compose -f docker-compose.casaos.yml up -d
+   ```
+
+3. **Check logs:**
+   ```bash
+   docker-compose -f docker-compose.casaos.yml logs -f
+   ```
+
+## Configuration
+
+### Required Environment Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `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 |
+|----------|-------------|---------|
+| `POSTGRES_PASSWORD` | PostgreSQL password (change from default!) | `euchrepassword` |
+
+## Database Management
+
+### First-Time Setup
+
+1. The PostgreSQL container will automatically initialize on first run
+2. Database migrations will be applied automatically
+3. Default admin user can be created via script:
+
+   ```bash
+   docker exec -it euchre-camp node scripts/create-admin-via-api.js
+   ```
+
+### Accessing the Database
+
+```bash
+# Connect to PostgreSQL container
+docker exec -it euchre-camp-postgres psql -U euchre -d euchre_camp
+
+# List tables
+\dt
+
+# Exit
+\q
+```
+
+### Backing Up Data
+
+```bash
+# Backup PostgreSQL data
+docker exec euchre-camp-postgres pg_dump -U euchre 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,75 @@
+# CasaOS Optimized Docker Compose Configuration
+# This file is optimized for deployment on CasaOS
+# Usage: docker-compose -f docker-compose.casaos.yml up -d
+
+services:
+  app:
+    build:
+      context: .
+      target: runner
+    container_name: euchre-camp
+    ports:
+      - "3000:3000"
+    environment:
+      # Database Configuration
+      - 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 Configuration
+      # IMPORTANT: Set these via CasaOS environment variables!
+      - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET:-change-this-secret-in-production}
+      - BETTER_AUTH_URL=${BETTER_AUTH_URL:-http://localhost:3000}
+      
+      # Application Configuration
+      - NODE_ENV=production
+      
+      # Trusted Origins for Better Auth
+      # IMPORTANT: Update this with your CasaOS IP/hostname
+      - TRUSTED_ORIGINS=${TRUSTED_ORIGINS:-http://localhost:3000,http://127.0.0.1:3000}
+    
+    depends_on:
+      postgres:
+        condition: service_healthy
+    
+    volumes:
+      # Persist uploaded files and static content
+      - euchre_camp_app_data:/app/public/uploads
+    
+    restart: unless-stopped
+    
+    networks:
+      - euchre-network
+
+  postgres:
+    image: postgres:15-alpine
+    container_name: euchre-camp-postgres
+    environment:
+      - POSTGRES_DB=euchre_camp
+      - POSTGRES_USER=euchre
+      # IMPORTANT: Change this password in production!
+      - POSTGRES_PASSWORD=euchrepassword
+    ports:
+      - "5432:5432"
+    volumes:
+      - euchre_camp_postgres_data:/var/lib/postgresql/data
+      - ./scripts/init-postgres.sh:/docker-entrypoint-initdb.d/init-postgres.sh
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U euchre -d euchre_camp"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+    restart: unless-stopped
+    networks:
+      - euchre-network
+
+volumes:
+  euchre_camp_postgres_data:
+    driver: local
+  euchre_camp_app_data:
+    driver: local
+
+networks:
+  euchre-network:
+    driver: bridge