denverm/moyosapp_beta.0.0.3.3_beta1

Files

moyoza 1b0063955a first commit beta.0.0.3.3

2026-01-16 19:04:48 +02:00

28 KiB

Raw Permalink Blame History

Single Source of Truth - Moyos Wedding App

Version: 2.0
Last Updated: January 2025
Status: Production Ready
Purpose: Comprehensive documentation for the Moyos Wedding App

Overview
Architecture
Local Development Setup
Environment Configuration
Database & Supabase
Deployment (Proxmox)
Troubleshooting
Operations & Runbooks

Overview

Project Description

The Moyos Wedding App is a premium, invite-only wedding management platform built for Lerato Molema and Denver Moyo. It provides a "Shock & Awe" digital experience featuring glassmorphism design, real-time AI assistance, and immersive storytelling.

Design Language

Garden Sanctuary Aesthetic:

Palette: Sage Hint (#BFCFBB), Mint (#BFCFBB), Sage (#8EA58C), Moss (#738A6E), Evergreen (#344C3D)
Typography: Great Vibes (calligraphy), Inter (modern legibility)
Aesthetic: High-density glassmorphism, botanical parallax, liquid silver accents

Technology Stack

Frontend:

Next.js 16.1.1 (App Router)
React 19.2.1
TypeScript 5.x
Tailwind CSS 4
Radix UI & Shadcn UI
Framer Motion
Lucide React

Backend:

Node.js 20.x
Next.js API Routes
Prisma 7.2.0 (PostgreSQL ORM)
Supabase (Auth, Storage, Realtime)
Redis (required in production for rate limiting)

Infrastructure:

Self-hosted on Proxmox VE 8.x+
PostgreSQL (via Supabase or standalone)
Docker Compose (optional)
Nginx (reverse proxy)
PM2 (process manager)

Development Tools:

npm (package manager)
ESLint (linting)
Jest & React Testing Library (testing)
Playwright (E2E testing)
TypeScript (type checking)
Sentry (error tracking)

Key Features

Guest RSVP System - Invite code authentication, RSVP submission with dietary preferences
Music Request & Voting - Apple Music integration, song requests, voting system
Photo Gallery - Guest photo uploads, moderation, comments, reactions
Guestbook - Text, audio, and video guestbook entries
Guest Directory - "Who's Who" directory with opt-in profiles
Admin Dashboard - Comprehensive wedding management
Real-time Updates - WebSocket/SSE integration for live updates
PWA Support - Progressive Web App with offline capabilities
AI Concierge - Self-hosted Ollama integration (optional)
Wedding Information Hub - Timeline, venue, dress code, FAQs

Architecture

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Client Browser                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │   Next.js    │  │   React 19   │  │  Tailwind   │       │
│  │  App Router  │  │  Components  │  │     CSS     │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
└───────────────────────┬─────────────────────────────────────┘
                        │ HTTPS
┌───────────────────────▼─────────────────────────────────────┐
│                    Next.js Server                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │  API Routes  │  │  Server      │  │  Middleware  │       │
│  │  (67 routes) │  │  Components  │  │  (Auth/CSRF) │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
└───────────────────────┬─────────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        │               │               │
┌───────▼──────┐ ┌─────▼──────┐ ┌─────▼──────┐
│  PostgreSQL  │ │  Supabase   │ │   Redis    │
│   (Prisma)   │ │   (Auth)    │ │  (Cache)   │
└──────────────┘ └─────────────┘ └─────────────┘

Directory Structure

app/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── (auth)/             # Protected routes
│   │   │   ├── dashboard/      # Guest dashboard
│   │   │   └── rsvp/           # RSVP page
│   │   ├── (public)/           # Public routes
│   │   │   └── wedding/        # Wedding info hub
│   │   ├── admin/              # Admin dashboard
│   │   ├── api/                # API routes
│   │   └── invite/            # Invite code entry
│   ├── components/
│   │   ├── features/           # Feature components
│   │   ├── layout/             # Layout components
│   │   └── ui/                 # Reusable UI components
│   ├── context/                # React Context
│   ├── hooks/                  # Custom hooks
│   ├── lib/                    # Utilities and services
│   └── types/                  # TypeScript definitions
├── prisma/
│   ├── schema.prisma          # Database schema
│   └── migrations/             # Database migrations
├── supabase/                   # Supabase configuration
│   └── migrations/             # Supabase migrations
├── public/                     # Static assets
└── scripts/                    # Deployment scripts

Data Flow

Guest Authentication Flow:

Guest → Invite Code Entry → POST /api/guest/auth
  → Validate Code → Create Session → Set Cookie
  → Return Guest Data → Update Context → Redirect to Dashboard

RSVP Submission Flow:

Guest → RSVP Form → POST /api/rsvp/submit
  → Verify CSRF → Check Rate Limit → Validate Input
  → Sanitize Data → Save to Database → Send Confirmation
  → Update Context → Show Success Message

Real-time Updates:

Event (RSVP/Music/Gallery) → Database Change
  → Supabase Realtime → WebSocket Broadcast
  → Client Receives Update → UI Refresh

Database Schema

Key Models:

Guest - Guest information, RSVP status, preferences
Song - Music requests with voting
SongVote - Individual votes on songs
GuestbookEntry - Guestbook messages (text/audio/video)
GalleryPhoto - Photo uploads with moderation
PhotoComment - Comments on photos
Table - Seating table assignments
Admin - Admin users with TOTP support

See prisma/schema.prisma for complete schema definition.

Local Development Setup

Prerequisites

Node.js: 20.x or later
npm: 10.x or later (or yarn/pnpm)
PostgreSQL: 14+ (or Supabase account)
Git: For version control

Installation Steps

Clone the repository:

git clone <repository-url>
cd moyosApp/app

Install dependencies:
```
npm install
```

Set up environment variables:

cp .env.local.example .env.local
# Edit .env.local with your configuration

See Environment Configuration for details.

Generate Prisma client:

npm run dev
# This automatically runs: prisma generate && next dev

Set up database:

# For development (creates schema)
npm run db:push

# For production (runs migrations)
npm run db:migrate

Seed database (optional):
```
npm run db:seed
```
Start development server:
```
npm run dev
```
Open in browser:
```
http://localhost:3000
```

Development Commands

# Development server
npm run dev

# Type checking
npm run typecheck

# Linting
npm run lint

# Testing
npm test
npm run test:watch
npm run test:coverage

# E2E testing
npm run test:e2e
npm run test:e2e:ui

# Database
npm run db:studio        # Prisma Studio
npm run db:push          # Push schema changes
npm run db:migrate       # Run migrations
npm run db:seed          # Seed database
npm run db:reset         # Reset database

# Build
npm run build
npm run start            # Production server

# Security
npm run security:audit
npm run security:audit:fix

Local Supabase Setup (Optional)

For local development with Supabase:

Install Supabase CLI:
```
npm install -g supabase
```
Initialize Supabase:
```
supabase init
```
Start local Supabase:
```
supabase start
```
Get local credentials:
```
supabase status
```

Update .env.local:

NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=<from supabase status>
SUPABASE_SERVICE_ROLE_KEY=<from supabase status>
DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres

See Database & Supabase for more details.

Environment Configuration

Required Variables

Authentication & Security

ADMIN_PASSWORD

Type: String
Required: Yes
Min Length: 8 characters
Default (Dev): wedding2026admin
Description: Password for admin dashboard access
Security: Must be changed in production
Example: StrongPassword123!

SESSION_SECRET

Type: String
Required: Yes
Min Length: 32 characters
Description: Secret key for session encryption
Security: Must be strong random string in production
Generation: openssl rand -base64 32
Example: f3ERSdncczdgAruOxCKXqqd5O6KIn81VQDlZ0nOARteUQ9nq6YBJi6MqJgzqazVQ

Database

DATABASE_URL

Type: PostgreSQL Connection String
Required: Yes (Production), No (Development)
Format: postgresql://user:password@host:port/database
Description: PostgreSQL database connection string
Example: postgresql://wedding_user:password@localhost:5432/wedding_db
Note: Direct connection (port 5432)

SHADOW_DATABASE_URL (Optional)

Type: PostgreSQL Connection String
Required: No
Description: Shadow database for Prisma migrations (Supabase)
Note: Only needed for Supabase migrations

RUNTIME_DATABASE_URL (Optional)

Type: PostgreSQL Connection String
Required: No
Default: DATABASE_URL
Description: Runtime database URL (pgbouncer, port 6543)
Use Case: Production connection pooling

Supabase

NEXT_PUBLIC_SUPABASE_URL

Type: URL String
Required: Yes
Description: Supabase project URL
Example: https://your-project-id.supabase.co
Local: http://127.0.0.1:54321

NEXT_PUBLIC_SUPABASE_ANON_KEY

Type: String
Required: Yes
Description: Supabase anonymous/public key (safe for client-side)
Note: Exposed to browser, use anon key only

SUPABASE_SERVICE_ROLE_KEY

Type: String
Required: Yes
Description: Supabase service role key (server-side only)
Security: NEVER expose to client - server-side only
Note: Has admin privileges, keep secret

Optional Variables

NEXT_PUBLIC_APP_URL

Type: URL String
Required: No
Default: http://localhost:3000
Description: Public URL of the application
Example: https://themoyos.co.za
Usage: Used for absolute URLs, email links, etc.

NODE_ENV

Type: Enum (development | production | test)
Required: No
Default: development
Description: Node.js environment

CSRF_SECRET

Type: String
Required: Yes (Production)
Default: None
Description: CSRF token secret
Generation: openssl rand -base64 24

SMTP Settings (Optional, for email notifications)

SMTP_HOST - SMTP server hostname (e.g., smtp.sendgrid.net)
SMTP_PORT - SMTP server port (e.g., 587)
SMTP_USER - SMTP username (e.g., apikey)
SMTP_PASS - SMTP password/API key

Twilio Settings (Optional, for SMS notifications)

TWILIO_ACCOUNT_SID - Twilio account SID
TWILIO_AUTH_TOKEN - Twilio auth token
TWILIO_PHONE_NUMBER - Twilio phone number

Redis (Required in production, for rate limiting)

REDIS_URL - Redis connection string (e.g., redis://localhost:6379)

Error Tracking & Analytics (Optional)

NEXT_PUBLIC_SENTRY_DSN - Sentry error tracking DSN
NEXT_PUBLIC_GA_MEASUREMENT_ID - Google Analytics Measurement ID

Feature Flags

ENABLE_NOTIFICATIONS - Enable email/SMS notifications (default: true)
ENABLE_ANALYTICS - Enable analytics tracking (default: false)

Environment-Specific Configuration

Development (`.env.local`)

# Required
ADMIN_PASSWORD=wedding2026admin
SESSION_SECRET=your-dev-secret-here-min-32-chars

# Database (optional in dev)
# DATABASE_URL=postgresql://user:pass@localhost:5432/wedding_db

# Supabase (local or cloud)
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-key

# Optional
NEXT_PUBLIC_APP_URL=http://localhost:3000
NODE_ENV=development
ENABLE_NOTIFICATIONS=true
ENABLE_ANALYTICS=false

Production (`.env.production`)

# Required
ADMIN_PASSWORD=your-strong-production-password
SESSION_SECRET=your-strong-random-secret-min-32-chars
DATABASE_URL=postgresql://user:pass@host:5432/wedding_db
NEXT_PUBLIC_APP_URL=https://themoyos.co.za

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-production-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-production-service-key

# Optional but Recommended
NEXT_PUBLIC_SENTRY_DSN=https://your-sentry-dsn
NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX

# Redis (REQUIRED for rate limiting in production)
REDIS_URL=redis://your-redis-host:6379

# Email (if using)
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASS=your-sendgrid-api-key

# Feature Flags
ENABLE_NOTIFICATIONS=true
ENABLE_ANALYTICS=true
NODE_ENV=production

# Ollama AI (Wedding Concierge)
# Use internal Docker network URL if Ollama is in same Coolify stack
# Or external URL if Ollama is on a different service
OLLAMA_URL=http://ollama-CONTAINER_ID:11434
# Or: OLLAMA_URL=https://ollama.yourdomain.com
OLLAMA_MODEL=jarvis-concierge
OLLAMA_TEMPERATURE=0.7

Security Best Practices

Never Commit Secrets
- .env.local is in .gitignore
- .env.production should never be committed
- Use .env.example for documentation
Strong Secrets
- SESSION_SECRET: Use openssl rand -base64 32
- ADMIN_PASSWORD: Minimum 12 characters, mix of letters, numbers, symbols
- Database passwords: Strong, unique passwords
Security Headers & CSP
- Single Source of Truth: All security headers (CSP, CORS, HSTS, etc.) are set in src/proxy.ts middleware
- Why Middleware: Middleware runs for all routes (pages and API), ensuring consistent security headers
- Do NOT set headers in next.config.ts: This would create conflicts and maintenance issues
- CSP Policy: Configured in src/proxy.ts with route-specific permissions (e.g., camera/mic for guestbook/gallery)
- Headers Set:
  - Content-Security-Policy (CSP)
  - Cross-Origin-Opener-Policy (COOP)
  - Cross-Origin-Resource-Policy (CORP)
  - X-Frame-Options
  - X-Content-Type-Options
  - Referrer-Policy
  - Permissions-Policy (route-specific)
  - Strict-Transport-Security (production only)
Production Secrets
- Use secrets management service (AWS Secrets Manager, Vault)
- Rotate secrets regularly
- Use different secrets per environment
Public Variables
- NEXT_PUBLIC_* variables are exposed to client
- Only use for non-sensitive configuration
- Never put secrets in NEXT_PUBLIC_* variables

Validation

All environment variables are validated using Zod schema in src/lib/env.ts.

Validation happens:

On application startup
Type checking
Format validation
Required field checking

Errors:

Invalid variables cause application to fail on startup
Clear error messages indicate which variables are invalid

Database & Supabase

Database Setup

Using Supabase (Recommended)

Create Supabase Project:
- Go to supabase.com
- Create a new project
- Wait for project to be ready
Get Connection String:
- Go to Settings → Database
- Copy the "Connection string" (URI format)
- Update DATABASE_URL in .env.local:
```
DATABASE_URL=postgresql://postgres:[YOUR-PASSWORD]@db.[YOUR-PROJECT-REF].supabase.co:5432/postgres
```
Get Supabase Keys:
- Go to Settings → API
- Copy Project URL → NEXT_PUBLIC_SUPABASE_URL
- Copy anon/public key → NEXT_PUBLIC_SUPABASE_ANON_KEY
- Copy service_role key → SUPABASE_SERVICE_ROLE_KEY
Run Migrations:
```
npm run db:migrate
```

Using Local PostgreSQL

Install PostgreSQL:

# macOS
brew install postgresql@14

# Ubuntu/Debian
sudo apt-get install postgresql-14

Create Database:
```
createdb wedding_app
```

Update DATABASE_URL:

DATABASE_URL=postgresql://postgres:password@localhost:5432/wedding_app

Run Migrations:
```
npm run db:migrate
```

Supabase Integration

Client-Side Usage

import { getSupabaseClient } from '@/lib/supabase';

// In a React component or client component
const supabase = getSupabaseClient();

// Example: Fetch data
const { data, error } = await supabase
  .from('guests')
  .select('*')
  .eq('isAttending', true);

// Example: Real-time subscription
const subscription = supabase
  .channel('guests')
  .on('postgres_changes', 
    { event: 'INSERT', schema: 'public', table: 'guests' },
    (payload) => {
      console.log('New guest added:', payload.new);
    }
  )
  .subscribe();

Server-Side Usage

import { createSupabaseAdminClient } from '@/lib/supabase';

// In API routes or server components
const supabase = createSupabaseAdminClient();

// Example: Admin operation
const { data, error } = await supabase
  .from('guests')
  .delete()
  .eq('id', guestId);

Database Migrations

Development:

# Push schema changes (creates migration automatically)
npm run db:push

# Or create migration manually
npx prisma migrate dev --name migration_name

Production:

# Run migrations
npm run db:migrate

Supabase Migrations:

# Create Supabase migration
supabase migration new migration_name

# Apply migrations
supabase db push

Database Management

Prisma Studio:

npm run db:studio

Seed Database:

npm run db:seed

Reset Database:

npm run db:reset

Deployment (Proxmox)

Prerequisites

Proxmox VE 8.x+ installed
Access to Proxmox web interface or CLI
Domain name configured (for SSL)
Basic Linux administration knowledge

Quick Deployment (30 minutes)

Step 1: Create LXC Containers

Next.js App Container:

pct create 190 \
  local:vztmpl/debian-12-standard_*.tar.zst \
  --hostname moyos-wedding-app \
  --memory 8192 \
  --cores 4 \
  --swap 2048 \
  --rootfs local-lvm:50 \
  --net0 name=eth0,bridge=vmbr0,ip=172.20.40.90/24,gw=172.20.40.1 \
  --unprivileged 1 \
  --start 1

Supabase Container/VM:

# Option A: LXC Container (if Docker support enabled)
pct create 191 \
  local:vztmpl/debian-12-standard_*.tar.zst \
  --hostname moyos-supabase \
  --memory 8192 \
  --cores 4 \
  --swap 2048 \
  --rootfs local-lvm:50 \
  --net0 name=eth0,bridge=vmbr0,ip=172.20.40.91/24,gw=172.20.40.1 \
  --privileged 1 \
  --start 1

# Option B: VM (Recommended for Docker)
# Create VM in Proxmox Web UI:
# - OS: Debian 12
# - Resources: 4 vCPU, 8GB RAM, 50GB disk
# - Network: Bridge (vmbr0)
# - IP: 172.20.40.91/24
# - Gateway: 172.20.40.1

Redis Container (Optional):

pct create 192 \
  local:vztmpl/debian-12-standard_*.tar.zst \
  --hostname moyos-redis \
  --memory 2048 \
  --cores 1 \
  --swap 512 \
  --rootfs local-lvm:10 \
  --net0 name=eth0,bridge=vmbr0,ip=172.20.40.92/24,gw=172.20.40.1 \
  --unprivileged 1 \
  --start 1

Step 2: Setup Next.js Container

# Enter container
pct enter 190

# Install Node.js & PM2
apt-get update && apt-get upgrade -y
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt-get install -y nodejs postgresql-client redis-tools git
npm install -g pm2
pm2 startup systemd

Step 3: Setup Supabase Container/VM

# SSH to VM or enter container
ssh root@172.20.40.91
# Or: pct enter 191

# Run Supabase setup script
cd /opt
git clone https://github.com/moyoza/moyosApp.git moyosApp
cd moyosApp/app
chmod +x scripts/*.sh
./scripts/setup-supabase-proxmox.sh

# Start Supabase
supabase start

# IMPORTANT: Save the keys from output!

Step 4: Deploy Application

# On Next.js container (190)
cd /opt
git clone https://github.com/moyoza/moyosApp.git moyosApp
cd moyosApp/app

# Configure environment
cp .env.local.example .env.production
nano .env.production  # Edit with your values

# Deploy
chmod +x scripts/*.sh
./scripts/deploy.sh --production

Required Environment Variables:

# Application
NODE_ENV="production"
NEXT_PUBLIC_APP_URL="https://your-domain.com"

# Supabase (self-hosted on Proxmox - pct 191)
NEXT_PUBLIC_SUPABASE_URL="http://172.20.40.91:54321"
NEXT_PUBLIC_SUPABASE_ANON_KEY="sb_publishable_<from-supabase-status>"
SUPABASE_SERVICE_ROLE_KEY="sb_secret_<from-supabase-status>"

# Database (from Supabase)
DATABASE_URL="postgresql://postgres:postgres@172.20.40.91:54322/postgres"

# Session & Security
SESSION_SECRET="your-32-char-secret"
CSRF_SECRET="your-csrf-secret"
ADMIN_PASSWORD="your-secure-admin-password"

# Redis (required)
REDIS_URL="redis://172.20.40.92:6379"

Step 5: Setup Nginx

# On host or Nginx container
apt-get update && apt-get install -y nginx certbot python3-certbot-nginx

# Copy config
cp /opt/moyos-wedding-app/app/nginx.conf /etc/nginx/sites-available/moyos-wedding-app

# Update domain name
sed -i 's/your-domain.com/actual-domain.com/g' /etc/nginx/sites-available/moyos-wedding-app

# Enable site
ln -s /etc/nginx/sites-available/moyos-wedding-app /etc/nginx/sites-enabled/
rm -f /etc/nginx/sites-enabled/default

# Test and reload
nginx -t
systemctl reload nginx

# Get SSL certificate
certbot --nginx -d your-domain.com -d www.your-domain.com

Post-Deployment

Verify Deployment:

# Health check
curl https://your-domain.com/api/health

# Run smoke tests
cd /opt/moyos-wedding-app/app
./scripts/smoke-tests.sh --base-url https://your-domain.com

Setup Backups:

# Add to crontab
crontab -e

# Database backup (daily at 2 AM)
0 2 * * * /opt/moyos-wedding-app/app/scripts/backup-db.sh

# Storage backup (daily at 3 AM)
0 3 * * * /opt/moyos-wedding-app/app/scripts/backup-storage.sh

Monitor Application:

# PM2 status
pm2 status

# View logs
pm2 logs moyos-wedding-app

# Monitor resources
pm2 monit

# Health check
./scripts/health-check.sh

Detailed Deployment Procedures

For comprehensive deployment procedures, see:

Deployment Runbook - Detailed step-by-step procedures
Backup Procedures - Backup and restore procedures

Troubleshooting

Common Issues

Application Won't Start

Symptoms: PM2 shows app as "errored" or "stopped"

Solutions:

# Check logs
pm2 logs moyos-wedding-app --err

# Check environment
cat .env.production

# Verify database connection
psql $DATABASE_URL -c "SELECT 1;"

# Restart
pm2 restart moyos-wedding-app

Database Connection Issues

Symptoms: "Database connection failed" errors

Solutions:

# Test connection from app container
psql -h 172.20.40.91 -p 54322 -U postgres -d postgres

# Check Supabase status (on Supabase container)
supabase status

# Check Supabase logs
supabase logs

# Verify firewall rules
iptables -L -n

Nginx Errors

Symptoms: 502 Bad Gateway, connection refused

Solutions:

# Test configuration
nginx -t

# Check error logs
tail -f /var/log/nginx/error.log

# Reload
systemctl reload nginx

useSearchParams Error (Turbopack)

Symptoms: useSearchParams is not defined runtime error

Solutions:

# Stop dev server
# Press Ctrl+C

# Clear build cache
rm -rf .next

# Restart dev server
npm run dev

Build Errors

Symptoms: Build fails with TypeScript or dependency errors

Solutions:

# Clean install
rm -rf node_modules package-lock.json
npm install

# Regenerate Prisma client
npx prisma generate

# Type check
npm run typecheck

# Build
npm run build

Environment Variable Issues

Symptoms: "Environment variable validation failed"

Solutions:

Check all required variables are set
Verify variable formats (URLs, booleans)
Check for typos in variable names
Ensure SESSION_SECRET is at least 32 characters
Verify DATABASE_URL format: postgresql://user:password@host:port/database

Getting Help

Check application logs: pm2 logs moyos-wedding-app
Check Nginx logs: tail -f /var/log/nginx/error.log
Check database logs: supabase logs
Review Deployment Runbook troubleshooting section
Check GitHub issues or documentation

Operations & Runbooks

Backup Procedures

Automated Backups:

Database: Daily at 2:00 AM
Storage: Daily at 3:00 AM
Configuration: Weekly (Sunday at 1:00 AM)

Manual Backup:

# Database backup
./scripts/backup-db.sh

# Storage backup
./scripts/backup-storage.sh

Restore:

# Restore database
./scripts/restore-db.sh /opt/backups/db/wedding_app_backup_YYYYMMDD_HHMMSS.sql.gz

For detailed backup procedures, see Backup Procedures.

Monitoring

Health Checks:

# Application health
curl https://your-domain.com/api/health

# Metrics
curl https://your-domain.com/api/metrics

# Automated health check script
./scripts/health-check.sh

PM2 Monitoring:

# Status
pm2 status

# Logs
pm2 logs moyos-wedding-app

# Monitor
pm2 monit

Maintenance

Update Application:

# Pull latest code
git pull origin main

# Install dependencies
npm ci --production=false

# Run migrations
npm run db:migrate

# Build
npm run build

# Restart
pm2 reload moyos-wedding-app

Update Dependencies:

# Check for updates
npm outdated

# Update dependencies
npm update

# Security audit
npm run security:audit
npm run security:audit:fix

Useful Commands

# Application
pm2 status                    # Check status
pm2 logs moyos-wedding-app    # View logs
pm2 restart moyos-wedding-app # Restart
pm2 monit                     # Monitor

# Database
psql $DATABASE_URL            # Connect to database
./scripts/backup-db.sh        # Backup database
./scripts/restore-db.sh <file> # Restore database

# Deployment
./scripts/deploy.sh --production  # Deploy
./scripts/health-check.sh          # Health check
./scripts/smoke-tests.sh          # Smoke tests

# Nginx
nginx -t                      # Test config
systemctl reload nginx        # Reload
systemctl status nginx       # Status

Additional Resources

Documentation Index - Complete documentation index
Deployment Runbook - Detailed deployment procedures
Backup Procedures - Backup and restore procedures
Coding Standards - Development guidelines

Last Updated: January 2025
Maintained By: Development Team
Questions? Check DOCS_INDEX.md or create an issue.

28 KiB Raw Permalink Blame History

Single Source of Truth - Moyos Wedding App

Table of Contents

Overview

Project Description

Design Language

Technology Stack

Key Features

Architecture

System Architecture

Directory Structure

Data Flow

Database Schema

Local Development Setup

Prerequisites

Installation Steps

Development Commands

Local Supabase Setup (Optional)

Environment Configuration

Required Variables

Authentication & Security

Database

Supabase

Optional Variables

Environment-Specific Configuration

Development (.env.local)

Production (.env.production)

Security Best Practices

Validation

Database & Supabase

Database Setup

Using Supabase (Recommended)

Using Local PostgreSQL

Supabase Integration

Client-Side Usage

Server-Side Usage

Database Migrations

Database Management

Deployment (Proxmox)

Prerequisites

Quick Deployment (30 minutes)

Step 1: Create LXC Containers

Step 2: Setup Next.js Container

Step 3: Setup Supabase Container/VM

Step 4: Deploy Application

Step 5: Setup Nginx

Post-Deployment

Detailed Deployment Procedures

Troubleshooting

Common Issues

Application Won't Start

Database Connection Issues

Nginx Errors

useSearchParams Error (Turbopack)

Build Errors

Environment Variable Issues

Getting Help

Operations & Runbooks

Backup Procedures

Monitoring

Maintenance

Useful Commands

Additional Resources

28 KiB

Raw Permalink Blame History

Development (`.env.local`)

Production (`.env.production`)