euchre_camp/docs/deployment/CASAOS_DEPLOYMENT.md

# 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