euchre_camp/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)

## 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