punimtag/viewer-frontend/docs/PREREQUISITES.md

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:

  # Using nvm (recommended)
  nvm install 20
  nvm use 20
  
  # Or download from https://nodejs.org/
  

• Verification:

  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:

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

  psql --version
  

• Requirements:
  • PunimTag database schema must be set up
  • Database must contain the photos table with media_type field
  • See 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 in README

4. npm (Node Package Manager)

• Included with: Node.js installation
• Why: Required to install project dependencies
• Verification:

  npm --version
  

Optional Prerequisites

5. FFmpeg (for Video Thumbnails)

• Version: Any recent version
• Why: Generates thumbnails for video files in the photo grid
• Installation:

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

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

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

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

  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
  2. Create an API key in your dashboard
  3. Add to .env:

     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 for detailed instructions

Development Tools (Optional)

9. Git

• Why: Version control (if cloning from repository)
• Installation:

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

  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:

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

   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:

   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:

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

# 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 in README

Next Steps

After installing prerequisites:

1. Follow the Quick Start Guide in README
2. Set up Environment Variables
3. Configure Database Permissions
4. See FFmpeg Setup if you want video thumbnails
5. See Network Share Setup if using photo uploads

Related Documentation

• README.md - Main setup guide
• FFmpeg Setup Guide - Video thumbnail setup
• Network Share Setup - Photo upload storage
• Video Viewing Analysis - Video feature details