tt-booking/docs/DEPLOYMENT_GUIDE.md

# Deployment Strategy for Table Tennis Booking System

## Overview

This document outlines comprehensive deployment strategies for the Table Tennis Booking System, considering both self-hosting and cloud deployment options. The application is a Next.js-based system with SQLite database, designed for production use.

## 1. Self-Hosting Strategy

### Option A: Raspberry Pi + Cloudflare Tunnel (Recommended)

**Architecture:**

```
Internet → Cloudflare → Cloudflare Tunnel → Raspberry Pi → Docker Container
```

**Requirements:**

-   Raspberry Pi 4 (4GB+ RAM recommended)
-   Stable internet connection
-   Cloudflare account (free tier sufficient)
-   Domain name (can be managed through Cloudflare)

**Setup Steps:**

1. **Raspberry Pi Preparation**

    ```bash
    # Update system
    sudo apt update && sudo apt upgrade -y

    # Install Docker
    curl -fsSL https://get.docker.com -o get-docker.sh
    sudo sh get-docker.sh
    sudo usermod -aG docker $USER

    # Install Docker Compose
    sudo apt install docker-compose -y
    ```

2. **Application Deployment**

    ```bash
    # Clone repository
    git clone <your-repo-url>
    cd tt-booking

    # Create production environment file
    cp .env.example .env.production
    # Edit .env.production with your values

    # Deploy with Docker
    docker-compose -f docker-compose.production.yml up -d
    ```

3. **Cloudflare Tunnel Setup**

    ```bash
    # Install cloudflared
    wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-arm64.deb
    sudo dpkg -i cloudflared-linux-arm64.deb

    # Authenticate
    cloudflared tunnel login

    # Create tunnel
    cloudflared tunnel create tt-booking

    # Configure tunnel (create config.yml)
    cloudflared tunnel route dns tt-booking yourdomain.com

    # Run tunnel
    cloudflared tunnel run tt-booking
    ```

**Cloudflare Tunnel Config (`~/.cloudflared/config.yml`):**

```yaml
tunnel: <tunnel-id>
credentials-file: /home/pi/.cloudflared/<tunnel-id>.json

ingress:
    - hostname: yourdomain.com
      service: http://localhost:3000
    - service: http_status:404
```

**Production Docker Compose (`docker-compose.production.yml`):**

```yaml
version: '3.8'

services:
    tt-booking:
        build: .
        ports:
            - '3000:3000'
        environment:
            - NODE_ENV=production
            - DATABASE_URL=/app/data/sqlite.db
            - NEXTAUTH_URL=https://yourdomain.com
            - NEXTAUTH_SECRET=${NEXTAUTH_SECRET}
            - EMAIL_USER=${EMAIL_USER}
            - EMAIL_PASSWORD=${EMAIL_PASSWORD}
            - ADMIN_EMAIL=${ADMIN_EMAIL}
            - ADMIN_PASSWORD=${ADMIN_PASSWORD}
        volumes:
            - ./data:/app/data
            - ./backups:/app/backups
        restart: unless-stopped
        healthcheck:
            test: ['CMD', 'curl', '-f', 'http://localhost:3000/api/health']
            interval: 30s
            timeout: 10s
            retries: 3

    # Backup service
    backup:
        image: alpine:latest
        volumes:
            - ./data:/data:ro
            - ./backups:/backups
        command: >
            sh -c "
            while true; do
              cp /data/sqlite.db /backups/sqlite-$(date +%Y%m%d-%H%M%S).db
              find /backups -name 'sqlite-*.db' -mtime +7 -delete
              sleep 86400
            done"
        restart: unless-stopped
```

**Advantages:**

-   No need for port forwarding or exposing home IP
-   Free SSL certificates through Cloudflare
-   DDoS protection and CDN benefits
-   Easy domain management
-   Cost-effective (only domain cost ~$10-15/year)

**Disadvantages:**

-   Dependent on home internet stability
-   Limited by residential bandwidth
-   Requires basic Linux administration skills

### Option B: Traditional Self-Hosting with Reverse Proxy

**Architecture:**

```
Internet → Router/Firewall → Nginx → Docker Container
```

**Requirements:**

-   Dedicated server or powerful Raspberry Pi
-   Static IP address or Dynamic DNS service
-   SSL certificate (Let's Encrypt)
-   Port forwarding configuration

**Setup includes all the Docker setup above, plus:**

1. **Nginx Configuration**

    ```bash
    # Install Nginx
    sudo apt install nginx certbot python3-certbot-nginx

    # Configure SSL
    sudo certbot --nginx -d yourdomain.com
    ```

2. **Updated Docker Compose with Nginx**
   Use the existing [docker-compose.yml](docker-compose.yml) with Nginx service.

**Advantages:**

-   Full control over infrastructure
-   No dependency on third-party tunneling services
-   Better performance for local network access

**Disadvantages:**

-   Requires static IP or Dynamic DNS
-   More complex firewall/security configuration
-   SSL certificate management overhead

## 2. Cloud Deployment Strategies

### Option A: DigitalOcean App Platform (Recommended for Small Scale)

**Cost Estimate:** $12-25/month

**Features:**

-   Automatic deployments from Git
-   Built-in SSL certificates
-   Automatic scaling
-   Integrated monitoring

**Deployment:**

1. Connect GitHub repository
2. Configure environment variables
3. Add persistent volume for SQLite database
4. Deploy with zero-config

**Configuration:**

```yaml
# .do/app.yaml
name: tt-booking
services:
    - name: web
      source_dir: /
      github:
          repo: your-username/tt-booking
          branch: main
      run_command: npm start
      environment_slug: node-js
      instance_count: 1
      instance_size_slug: basic-xxs
      envs:
          - key: NODE_ENV
            value: production
          - key: DATABASE_URL
            value: /app/data/sqlite.db
```

### Option B: Railway (Developer-Friendly)

**Cost Estimate:** $5-20/month

**Features:**

-   Git-based deployments
-   Built-in databases available
-   Simple pricing model
-   Excellent developer experience

**Deployment:**

```bash
# Install Railway CLI
npm install -g @railway/cli

# Login and deploy
railway login
railway init
railway up
```

### Option C: Vercel + PlanetScale (Serverless)

**Cost Estimate:** $0-20/month (depending on usage)

**Modifications needed:**

-   Replace SQLite with PlanetScale MySQL
-   Update database schema for MySQL compatibility
-   Modify connection configuration

**Deployment:**

```bash
# Install Vercel CLI
npm install -g vercel

# Deploy
vercel --prod
```

### Option D: AWS/GCP/Azure (Enterprise Scale)

**Cost Estimate:** $30-100+/month

**AWS Deployment Options:**

1. **ECS Fargate + RDS**

    - Container-based deployment
    - Managed database
    - Auto-scaling capabilities

2. **Elastic Beanstalk**

    - Simple deployment model
    - Built-in monitoring
    - Easy environment management

3. **App Runner**
    - Serverless container platform
    - Automatic scaling
    - Pay-per-use pricing

## 3. Database Considerations

### For Self-Hosting

-   **SQLite**: Perfect for small to medium loads
-   **Backup Strategy**: Automated daily backups to external storage
-   **Monitoring**: Simple file-based health checks

### For Cloud Deployment

-   **Small Scale**: Keep SQLite with persistent volumes
-   **Medium Scale**: PostgreSQL (Railway, DigitalOcean Managed DB)
-   **Large Scale**: Multi-region database (AWS RDS, Google Cloud SQL)

## 4. Monitoring and Maintenance

### Essential Monitoring

```bash
# Add to crontab for health checks
*/5 * * * * curl -f https://yourdomain.com/api/health || echo "App down" | mail -s "Alert" admin@example.com
```

### Backup Strategy

1. **Database Backups**: Daily automated SQLite file copies
2. **Environment Config**: Version controlled `.env` files
3. **Application Code**: Git-based source control

### Update Strategy

```bash
#!/bin/bash
# update.sh
cd /path/to/tt-booking
git pull origin main
docker-compose -f docker-compose.production.yml down
docker-compose -f docker-compose.production.yml up -d --build
```

## 5. Security Considerations

### Self-Hosting Security Checklist

-   [ ] Firewall configured (only necessary ports open)
-   [ ] Regular OS updates automated
-   [ ] Non-root user for application
-   [ ] SSL certificates properly configured
-   [ ] Database backups encrypted
-   [ ] Rate limiting configured (already in nginx.conf)
-   [ ] Log monitoring for suspicious activity

### Cloud Security

-   [ ] Environment variables properly secured
-   [ ] Database access restricted
-   [ ] API rate limiting enabled
-   [ ] Regular dependency updates
-   [ ] Security headers configured (already in app)

## 6. Cost Comparison

| Deployment Method         | Monthly Cost | Effort   | Scalability | Reliability |
| ------------------------- | ------------ | -------- | ----------- | ----------- |
| Raspberry Pi + CF Tunnel  | $1-2         | Medium   | Low         | Medium      |
| Traditional Self-Host     | $5-10        | High     | Low         | Medium      |
| DigitalOcean App Platform | $12-25       | Low      | Medium      | High        |
| Railway                   | $5-20        | Very Low | Medium      | High        |
| Vercel + PlanetScale      | $0-20        | Low      | High        | High        |
| AWS/GCP/Azure             | $30-100+     | High     | Very High   | Very High   |

## 7. Recommended Approach

### For Personal/Small Group Use:

**Raspberry Pi + Cloudflare Tunnel** - Most cost-effective with good reliability

### For Small Business:

**Railway or DigitalOcean App Platform** - Balance of simplicity and reliability

### For Enterprise:

**AWS/GCP with proper CI/CD pipeline** - Maximum scalability and reliability

## 8. Local Development Best Practices

### Standalone Development

```bash
# Quick development setup
npm install
npm run dev
```

### Docker Development

```bash
# Development with Docker
docker-compose up -d
```

### Production-like Local Testing

```bash
# Test production build locally
npm run build
npm start
```

## 9. Health Check Endpoint

The application includes a health check endpoint at `/api/health` for monitoring purposes. You should create this endpoint:

```typescript
// app/api/health/route.ts
import { NextResponse } from 'next/server';
import { db } from '@/lib/db';

export async function GET() {
	try {
		// Basic database connectivity check
		await db.select().from(settings).limit(1);

		return NextResponse.json({
			status: 'healthy',
			timestamp: new Date().toISOString(),
			uptime: process.uptime(),
		});
	} catch (error) {
		return NextResponse.json({ status: 'unhealthy', error: 'Database connection failed' }, { status: 500 });
	}
}
```

## 10. Environment Variables for Production

Create a `.env.production` file with the following required variables:

```bash
# Application
NODE_ENV=production
NEXTAUTH_URL=https://yourdomain.com
NEXTAUTH_SECRET=your-very-long-random-secret-here

# Database
DATABASE_URL=/app/data/sqlite.db

# Email Configuration (optional)
EMAIL_USER=your-email@gmail.com
EMAIL_PASSWORD=your-app-specific-password

# Admin Account
ADMIN_EMAIL=admin@yourdomain.com
ADMIN_PASSWORD=secure-admin-password

# Optional: Rate limiting
RATE_LIMIT_MAX=100
RATE_LIMIT_WINDOW=900000
```

## 11. Docker Production Optimization

Create a production-optimized `Dockerfile.production`:

```dockerfile
FROM node:18-alpine AS base

# Install dependencies only when needed
FROM base AS deps
WORKDIR /app
COPY package.json package-lock.json* ./
RUN npm ci --only=production && npm cache clean --force

# Rebuild the source code only when needed
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

# Production image, copy all the files and run next
FROM base AS runner
WORKDIR /app

ENV NODE_ENV production

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

# Copy built application
COPY --from=builder --chown=nextjs:nodejs /app/.next ./.next
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json
COPY --from=builder /app/public ./public

# Create data directory for SQLite
RUN mkdir -p /app/data && chown nextjs:nodejs /app/data

USER nextjs

EXPOSE 3000

ENV PORT 3000
ENV HOSTNAME "0.0.0.0"

CMD ["npm", "start"]
```

This deployment strategy provides multiple pathways depending on your technical expertise, budget, and scaling requirements. The Cloudflare Tunnel approach is particularly attractive for self-hosting as it eliminates many traditional networking complexities while maintaining security and reliability.