feat: Add new scripts and update project structure for database management and user authentication

This commit introduces several new scripts for managing database operations, including user creation, permission grants, and data migrations. It also adds new documentation files to guide users through the setup and configuration processes. Additionally, the project structure is updated to enhance organization and maintainability, ensuring a smoother development experience for contributors. These changes support the ongoing transition to a web-based architecture and improve overall project functionality.
2026-01-06 13:53:24 -05:00
parent 713584dc04
commit de2144be2a
175 changed files with 35854 additions and 0 deletions
@@ -0,0 +1,316 @@
+# 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
+
+
+
+
+
+
+