Wishlist Deployment & Usage Guide

1. Prerequisites

Required Software

• Docker and Docker Compose (recommended for production)
• Node.js 18+ and npm (for development)
• SQLite (included with Docker setup, no separate installation needed)

Optional Dependencies

• SMTP server (for email invitations)
• Reverse proxy (Nginx, Traefik, Caddy, or cloud-native load balancer)
• OAuth provider (Google, GitHub, etc. for OIDC authentication)

Accounts & Services

• Docker Hub/GitHub Container Registry account (for pulling images)
• SMTP service (SendGrid, Mailgun, Gmail, or self-hosted)
• Domain name (if exposing publicly)
• OAuth provider credentials (if using OIDC)

2. Installation

Docker Compose (Recommended for Production)

Create a docker-compose.yaml file:

services:
  wishlist:
    container_name: wishlist
    image: ghcr.io/cmintey/wishlist:latest
    ports:
      - 3280:3280
    volumes:
      - ./uploads:/usr/src/app/uploads  # User image uploads
      - ./data:/usr/src/app/data        # SQLite database
    environment:
      ORIGIN: http://192.168.2.10:3280  # Your actual URL
      TOKEN_TIME: 72

Start the application:

docker compose up -d

Access at: http://<your-host>:3280

Manual Installation (Development)

Clone and install dependencies:

git clone https://github.com/cmintey/wishlist.git
cd wishlist
npm install

Initialize the database:

npx prisma generate
npx prisma db push

3. Configuration

Environment Variables

Create a .env file or set environment variables in your Docker Compose:

SMTP Configuration (Email Invitations)

Enable in Admin Panel or set via environment variables:

• SMTP_HOST: Your SMTP server
• SMTP_PORT: SMTP port (usually 587 or 465)
• SMTP_USER: SMTP username
• SMTP_PASS: SMTP password
• SMTP_FROM: Sender email address
• SMTP_FROM_NAME: Sender display name

OAuth/OIDC Configuration

Configure in Admin Panel under Security settings:

• OIDC_ENABLE: true to enable
• OIDC_DISCOVERY_URL: Provider discovery URL
• OIDC_CLIENT_ID: OAuth client ID
• OIDC_CLIENT_SECRET: OAuth client secret
• OIDC_PROVIDER_NAME: Display name for provider
• OIDC_AUTO_REGISTER: Automatically register new users

Application Configuration via Admin Panel

Access configuration at /admin after login:

User Management:

• Enable/disable public signup
• Invite users via email (requires SMTP)
• Manage group permissions

Suggestion Settings:

• Enable/disable suggestions
• Choose method: Approval Required, Auto Approval, or Surprise Me

Claim Settings:

• Show claimer names
• Show names across groups
• Show claims to item owners
• Require email for claims

Security:

• Password strength requirements
• Disable password login (OIDC only)
• Default group assignment

4. Build & Run

Development Mode

npm run dev
# Access at http://localhost:5173

Production Build

npm run build
npm run preview
# Access at http://localhost:4173

Docker Build (Custom Image)

docker build -t wishlist:latest .
docker run -p 3280:3280 -v ./data:/usr/src/app/data wishlist:latest

5. Deployment

Docker-Based Deployments

• Docker Compose: Use the provided compose file for single-server deployment
• Kubernetes: Use the community Helm chart
• Docker Swarm: Adapt the compose file for swarm deployment

Reverse Proxy Setup

Nginx Configuration:

server {
    listen 80;
    server_name wishlist.example.com;
    
    location / {
        proxy_pass http://localhost:3280;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # Required for Nginx/Synology compatibility
        proxy_buffer_size 128k;
        proxy_buffers 4 256k;
        proxy_busy_buffers_size 256k;
    }
    
    # SSL configuration recommended
    listen 443 ssl;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
}

Cloud Platforms:

• Railway: Deploy with Dockerfile
• Fly.io: Use Docker deployment
• DigitalOcean App Platform: Docker container service
• AWS ECS: Container service with Fargate
• Google Cloud Run: Serverless containers

Persistent Storage

Ensure these directories are mounted as volumes:

• /usr/src/app/data - SQLite database
• /usr/src/app/uploads - User-uploaded images

6. Troubleshooting

Common Issues

1. "Invalid Origin" or CORS Errors

• Ensure ORIGIN environment variable matches the exact URL users access
• Include port number if using IP address: http://192.168.2.10:3280
• Restart container after changing ORIGIN

2. Nginx/Synology Proxy Issues Add to Nginx configuration:

proxy_buffer_size 128k;
proxy_buffers 4 256k;
proxy_busy_buffers_size 256k;

3. Email Invitations Not Sending

• Verify SMTP settings in Admin Panel
• Check container logs: docker logs wishlist
• Test SMTP credentials with a mail client
• Ensure port 587/465 is open in firewall

4. Image Uploads Failing

• Check MAX_IMAGE_SIZE environment variable (default 5MB)
• Verify uploads directory has write permissions: chmod 755 uploads
• Check available disk space

5. Database Issues

• Ensure /usr/src/app/data directory is mounted and writable
• Check SQLite file permissions: chown 1000:1000 data/wishlist.db
• Backup database regularly from mounted volume

6. OAuth/OIDC Login Failing

• Verify discovery URL is accessible
• Check client ID and secret are correct
• Ensure redirect URI matches: {ORIGIN}/auth/callback/oidc
• Check container logs for detailed error messages

Logs & Debugging

Docker Logs:

docker logs wishlist
docker logs wishlist --tail 50 -f  # Follow last 50 lines

Application Logs:

• Check browser console for frontend errors
• Review server logs in Docker container
• Enable debug logging via environment variables if needed

Database Maintenance

Backup SQLite Database:

docker exec wishlist sqlite3 /usr/src/app/data/wishlist.db ".backup /backup/wishlist-$(date +%Y%m%d).db"

Reset Admin Password: If locked out, you can reset via SQLite:

docker exec wishlist sqlite3 /usr/src/app/data/wishlist.db
UPDATE User SET password = 'new_hashed_password' WHERE email = 'admin@example.com';

Note: Use password hashing tools to generate proper bcrypt hashes for password resets.

Performance Issues

• Use reverse proxy with caching for static assets
• Monitor disk space for uploads directory
• Consider moving to PostgreSQL for larger deployments (requires code changes)
• Enable gzip compression in reverse proxy