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:

   docker-compose -f docker-compose.casaos.yml build
   

3. Start the application:

   docker-compose -f docker-compose.casaos.yml up -d
   

4. Check logs:

   docker-compose -f docker-compose.casaos.yml logs -f
   

PostgreSQL Database Setup

Option A: External PostgreSQL Server

Connect to your PostgreSQL server and run:

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

   docker exec -it euchre-camp npx prisma migrate deploy
   

3. Create admin user:

   docker exec -it euchre-camp node scripts/create-admin-via-api.js
   

Accessing the Database

# Connect to external PostgreSQL server
psql -h your-postgres-host -U euchre_camp -d euchre_camp

# List tables
\dt

# Exit
\q

Backing Up Data

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

   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

# 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

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

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

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:

# 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

docker-compose -f docker-compose.casaos.yml logs -f

Check Container Status

docker ps | grep euchre

Resource Usage

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