# Prerequisites

This document lists all software, tools, and services required to run the PunimTag Photo Viewer application.

## Required Prerequisites

### 1. Node.js
- **Version:** Node.js 20.9.0 or higher
- **Why:** Next.js 16 requires Node.js >=20.9.0
- **Installation:**
  ```bash
  # Using nvm (recommended)
  nvm install 20
  nvm use 20
  
  # Or download from https://nodejs.org/
  ```
- **Verification:**
  ```bash
  node --version  # Should show v20.x.x or higher
  npm --version
  ```

### 2. PostgreSQL Database
- **Version:** PostgreSQL 12 or higher
- **Why:** Required for storing photo metadata, faces, people, tags, and authentication data
- **Installation:**
  ```bash
  # Ubuntu/Debian
  sudo apt update
  sudo apt install postgresql postgresql-contrib
  
  # macOS
  brew install postgresql
  
  # Windows
  # Download from https://www.postgresql.org/download/windows/
  ```
- **Verification:**
  ```bash
  psql --version
  ```
- **Requirements:**
  - PunimTag database schema must be set up
  - Database must contain the `photos` table with `media_type` field
  - See [Database Setup](../README.md#database-setup) for details

### 3. Database Users
- **Read-only user** (required): For querying photos, faces, people, tags
- **Write user** (optional): For face identification and photo uploads
- **Setup:** See [Database Setup](../README.md#database-setup) in README

### 4. npm (Node Package Manager)
- **Included with:** Node.js installation
- **Why:** Required to install project dependencies
- **Verification:**
  ```bash
  npm --version
  ```

## Optional Prerequisites

### 5. FFmpeg (for Video Thumbnails)
- **Version:** Any recent version
- **Why:** Generates thumbnails for video files in the photo grid
- **Installation:**
  ```bash
  # Ubuntu/Debian
  sudo apt update
  sudo apt install ffmpeg
  
  # macOS
  brew install ffmpeg
  
  # Windows
  # Download from https://ffmpeg.org/download.html
  # Or: choco install ffmpeg
  ```
- **Verification:**
  ```bash
  ffmpeg -version
  ```
- **What happens without it:**
  - Videos will display a placeholder image (gray box with play icon)
  - Videos will still be viewable, but without thumbnails in the grid
  - Application continues to work normally
- **See:** [FFmpeg Setup Guide](./FFMPEG_SETUP.md) for detailed instructions

### 6. libvips (for Image Watermarking)
- **Version:** Any recent version
- **Why:** Required by the `sharp` npm package for image processing and watermarking
- **Installation:**
  ```bash
  # Ubuntu/Debian
  sudo apt update
  sudo apt install libvips-dev
  
  # macOS
  brew install vips
  
  # Windows
  # Download from https://www.libvips.org/install.html
  # Or: choco install vips
  ```
- **Verification:**
  ```bash
  # Check if library is available
  ldconfig -p | grep vips
  
  # Or check sharp installation
  cd viewer-frontend
  npm rebuild sharp
  ```
- **What happens without it:**
  - Image watermarking will be disabled
  - Images will be served without watermarks (original images still work)
  - Application continues to work normally
  - You'll see a warning in the console: "Sharp library not available"
- **Note:** After installing libvips, you may need to rebuild the sharp package:
  ```bash
  cd viewer-frontend
  npm rebuild sharp
  ```

### 7. Resend API Key (for Email Verification)
- **Why:** Required for email verification when users register
- **Setup:**
  1. Sign up at [resend.com](https://resend.com)
  2. Create an API key in your dashboard
  3. Add to `.env`:
     ```bash
     RESEND_API_KEY="re_your_api_key_here"
     RESEND_FROM_EMAIL="noreply@yourdomain.com"
     ```
- **What happens without it:**
  - Email verification will not work
  - Users cannot verify their email addresses
  - Registration may fail or require manual verification

### 8. Network-Accessible Storage (for Photo Uploads)
- **Why:** Required for storing uploaded photos before admin approval
- **Options:**
  - Database server via SSHFS
  - Network share (SMB/NFS)
  - Local directory (if database and web server are on same machine)
- **Configuration:** Set `UPLOAD_DIR` or `PENDING_PHOTOS_DIR` in `.env`
- **See:** [Network Share Setup](./NETWORK_SHARE_SETUP.md) for detailed instructions

## Development Tools (Optional)

### 9. Git
- **Why:** Version control (if cloning from repository)
- **Installation:**
  ```bash
  # Ubuntu/Debian
  sudo apt install git
  
  # macOS
  brew install git
  
  # Windows
  # Download from https://git-scm.com/download/win
  ```

### 10. OpenSSL (for Generating Secrets)
- **Why:** Used to generate secure `NEXTAUTH_SECRET`
- **Usually pre-installed** on Linux/macOS
- **Windows:** Usually included with Git for Windows
- **Usage:**
  ```bash
  openssl rand -base64 32
  ```

## System Requirements

### Operating System
- **Linux:** Ubuntu 20.04+, Debian 11+, or similar
- **macOS:** macOS 11 (Big Sur) or later
- **Windows:** Windows 10 or later (WSL2 recommended for development)

### Memory
- **Minimum:** 2GB RAM
- **Recommended:** 4GB+ RAM (for image processing and video thumbnail generation)

### Disk Space
- **Minimum:** 500MB for application
- **Additional:** Space for:
  - Video thumbnail cache (`.cache/video-thumbnails/`)
  - Uploaded photos (if using local storage)
  - Node modules (~500MB)

### Network
- **Required:** Access to PostgreSQL database
- **Optional:** Internet access for:
  - npm package installation
  - Resend API (email verification)
  - External photo storage (SharePoint, CDN, etc.)

## Quick Verification Checklist

Run these commands to verify all prerequisites:

```bash
# Node.js
node --version  # Should be v20.x.x or higher
npm --version

# PostgreSQL
psql --version

# FFmpeg (optional)
ffmpeg -version  # Should show version or "command not found" (OK if optional)

# libvips (optional, for image watermarking)
ldconfig -p | grep vips  # Should show libvips or nothing (OK if optional)

# OpenSSL (for generating secrets)
openssl version

# Git (optional)
git --version
```

## Installation Order

1. **Install Node.js 20+**
2. **Install PostgreSQL** and set up database
3. **Create database users** (read-only, write if needed)
4. **Clone/download project**
5. **Install all dependencies** (recommended):
   ```bash
   npm run install:deps
   ```
   This automated script will:
   - Install npm dependencies
   - Set up Sharp library with proper library paths
   - Generate Prisma clients
   - Check and optionally install system dependencies (libvips, FFmpeg)
   
   **Or manually:**
   ```bash
   npm install
   npm run prisma:generate:all
   # Optional: Install system dependencies
   sudo apt install libvips-dev ffmpeg  # Ubuntu/Debian
   ```
6. **Set up environment variables** (`.env` file)
7. **Set up Resend API** (optional, for email verification)
8. **Configure upload directory** (if using photo uploads)

## Troubleshooting

### Node.js Version Issues
If you see errors about Node.js version:
```bash
# Check current version
node --version

# Install/switch to Node.js 20 using nvm
nvm install 20
nvm use 20
```

### PostgreSQL Connection Issues
- Verify PostgreSQL is running: `sudo systemctl status postgresql`
- Check database exists: `psql -U postgres -l`
- Verify connection string in `.env`

### FFmpeg Not Found
- See [FFmpeg Setup Guide](./FFMPEG_SETUP.md)
- Application will work without it (placeholders will be shown)

### Sharp/libvips Errors
If you see errors like "Could not load the sharp module" or "libvips-cpp.so.8.17.3: cannot open shared object file":

**Solution:** The install script (`npm run install:deps`) automatically sets up Sharp with the correct library paths. If you installed manually:

```bash
# Install libvips development libraries
sudo apt install libvips-dev  # Ubuntu/Debian
brew install vips  # macOS

# The wrapper script (scripts/with-sharp-libpath.sh) handles library paths automatically
# No manual rebuild needed - it's configured in package.json scripts
```

- The application uses a wrapper script to set `LD_LIBRARY_PATH` automatically
- If Sharp still fails, watermarking will be disabled but the app will continue working
- Images will be served without watermarks if Sharp is unavailable

### Permission Denied Errors
- Check database user permissions: `npm run check:permissions`
- See [Database Setup](../README.md#database-setup) in README

## Next Steps

After installing prerequisites:
1. Follow the [Quick Start Guide](../README.md#-quick-start) in README
2. Set up [Environment Variables](../README.md#installation)
3. Configure [Database Permissions](../README.md#database-setup)
4. See [FFmpeg Setup](./FFMPEG_SETUP.md) if you want video thumbnails
5. See [Network Share Setup](./NETWORK_SHARE_SETUP.md) if using photo uploads

## Related Documentation

- [README.md](../README.md) - Main setup guide
- [FFmpeg Setup Guide](./FFMPEG_SETUP.md) - Video thumbnail setup
- [Network Share Setup](./NETWORK_SHARE_SETUP.md) - Photo upload storage
- [Video Viewing Analysis](./VIDEO_VIEWING_ANALYSIS.md) - Video feature details