diff --git a/DEPLOYMENT_GUIDE.md b/DEPLOYMENT_GUIDE.md index 9d13a68d..3e0cbece 100644 --- a/DEPLOYMENT_GUIDE.md +++ b/DEPLOYMENT_GUIDE.md @@ -2,9 +2,23 @@ This guide covers multiple deployment options for PicPeak, from simple local setups to production-ready configurations. -## 🎯 Quick Start - Simple Setup (Recommended for Beginners) +## 📋 Table of Contents -For the easiest installation without Docker or complex configurations, use our **unified setup script**: +- [Quick Start](#-quick-start) +- [Prerequisites](#prerequisites) +- [Configuration](#-configuration) +- [Deployment](#-deployment) +- [First Login](#-first-login) +- [Reverse Proxy Setup](#-reverse-proxy-setup) +- [External Media Library](#external-media-library) +- [Maintenance](#-maintenance) +- [Troubleshooting](#-troubleshooting) + +## 🚀 Quick Start + +### Option 1: Automated Setup Script (Easiest) + +For the simplest installation, use our unified setup script: ```bash curl -fsSL https://raw.githubusercontent.com/the-luap/picpeak/main/scripts/picpeak-setup.sh -o picpeak-setup.sh && \ @@ -12,27 +26,11 @@ chmod +x picpeak-setup.sh && \ sudo ./picpeak-setup.sh ``` -This automated script handles everything including: -- Choice between Docker or Native installation -- OS detection and dependency installation -- Database setup and service configuration -- SSL/HTTPS setup (optional) - -Perfect for: -- Small to medium deployments -- Local or VPS installations -- Users new to server management -- Quick testing and evaluation +This script handles Docker/Native installation choice, OS detection, dependencies, database setup, and optional SSL. 👉 **See [SIMPLE_SETUP.md](./SIMPLE_SETUP.md) for detailed instructions.** ---- - -## 🐳 Docker Compose Deployment - -### Option 1: Using Pre-built Images (Recommended) - -PicPeak provides official Docker images via GitHub Container Registry for quick deployment without building: +### Option 2: Docker with Pre-built Images (Recommended) ```bash # Clone repository for configuration files @@ -43,35 +41,33 @@ cd picpeak cp .env.example .env nano .env # Edit with your values -# Use pre-built images deployment +# Create required directories +mkdir -p events/active events/archived data logs backup storage +chmod -R 755 events data logs backup storage + +# Deploy using pre-built images docker compose -f docker-compose.production.yml up -d + +# Check logs +docker compose -f docker-compose.production.yml logs -f ``` -The production compose file uses: -- **Backend**: `ghcr.io/the-luap/picpeak/backend:latest` -- **Frontend**: `ghcr.io/the-luap/picpeak/frontend:latest` +Available image tags: `latest` (stable), `main`, `develop`, `v1.0.0` (version tags) -Available tags: -- `latest` - Latest stable release -- `main` - Latest main branch build -- `develop` - Development branch (may be unstable) -- `v1.0.0` - Specific version tags +### Option 3: Build from Source -### Option 2: Building from Source +```bash +git clone https://github.com/the-luap/picpeak.git +cd picpeak +cp .env.example .env +nano .env # Edit with your values -If you need to customize the application or the pre-built images aren't available, you can build locally: +mkdir -p events/active events/archived data logs backup storage +chmod -R 755 events data logs backup storage -## 📋 Table of Contents - -- [Prerequisites](#prerequisites) -- [Quick Start](#quick-start) -- [Configuration](#configuration) -- [Deployment](#deployment) -- [First Login](#first-login) -- [Reverse Proxy Setup](#reverse-proxy-setup) -- [Maintenance](#maintenance) -- [Troubleshooting](#troubleshooting) - - [External Media Library](#external-media-library) +docker compose build +docker compose up -d +``` ## Prerequisites @@ -80,106 +76,6 @@ If you need to customize the application or the pre-built images aren't availabl - SMTP server credentials for emails - At least 2GB RAM and 20GB storage -## 🚀 Quick Start - -### Method 1: Using Pre-built Images (Fastest) - -1. **Clone the repository for configs** - ```bash - git clone https://github.com/the-luap/picpeak.git - cd picpeak - ``` - -2. **Set up environment** - ```bash - cp .env.example .env - nano .env # Edit with your values - ``` - -3. **Create required directories** - ```bash - mkdir -p events/active events/archived data logs backup storage - chmod -R 755 events data logs backup storage - ``` - -4. **Deploy using pre-built images** - ```bash - docker compose -f docker-compose.production.yml up -d - ``` - -5. **Check logs** - ```bash - docker compose -f docker-compose.production.yml logs -f - ``` - -## External Media Library - -PicPeak can reference an existing, read‑only media library mounted into the backend container. This avoids copying originals into PicPeak storage. - -- Map your host library path to the container as read‑only in `docker-compose.production.yml`: - - Add volume under `backend`: `- ${EXTERNAL_MEDIA}:/external-media:ro` - - Add backend env: `EXTERNAL_MEDIA_ROOT=/external-media` -- In `.env`, set: - - `EXTERNAL_MEDIA=/mnt/photos` (example host path) - - `EXTERNAL_MEDIA_ROOT=/external-media` - -Usage: -- In Admin → Events, set “Source Mode” to “Reference (external folder)”, select a folder under `/external-media`, then import to index and generate thumbnails. Originals stay in your library. - -Backups and Archives: -- Backups only include data under `STORAGE_PATH` and exclude external originals. The backup manifest includes `metadata.external_references = { excluded: true, events: N, photos: M }` and the Admin UI surfaces a warning. -- Archiving reference events creates a manifest‑only ZIP and deletes thumbnails for that event. External originals are never moved or deleted. - -Local (npm) setup (no Docker): - -1. Create or choose a folder that contains your external originals, e.g. `/Users/you/Pictures/picpeak-external` (macOS/Linux) or `C:\\Pictures\\picpeak-external` (Windows). -2. In `backend/.env` (or your shell), set: - - `EXTERNAL_MEDIA_ROOT=/absolute/path/to/picpeak-external` - - Ensure `STORAGE_PATH` points to your PicPeak storage (defaults to `./storage`). -3. Start services from source: - - Backend: `cd backend && npm install && npm run migrate && JWT_SECRET=... npm start` - - Frontend: `cd frontend && npm install && npm run dev` (or build + serve) -4. In Admin → Events: - - Create an event, set “Source Mode” to “Reference (external folder)”. - - Use the folder picker to browse under your `EXTERNAL_MEDIA_ROOT` and select the subfolder to reference. - - Click “Import from selected folder” to index files and generate thumbnails on demand. - -Notes: -- PicPeak only reads from `EXTERNAL_MEDIA_ROOT`; it never modifies or deletes your originals there. -- Thumbnails are generated under `STORAGE_PATH/thumbnails` and are included in backups; originals in `EXTERNAL_MEDIA_ROOT` are excluded. -- On Windows, use absolute paths (e.g., `C:\\Photos\\Library`) for `EXTERNAL_MEDIA_ROOT`. - -### Method 2: Building from Source - -1. **Clone the repository** - ```bash - git clone https://github.com/the-luap/picpeak.git - cd picpeak - ``` - -2. **Set up environment** - ```bash - cp .env.example .env - nano .env # Edit with your values - ``` - -3. **Create required directories** - ```bash - mkdir -p events/active events/archived data logs backup storage - chmod -R 755 events data logs backup storage - ``` - -4. **Build and deploy** - ```bash - docker compose build - docker compose up -d - ``` - -5. **Check logs** - ```bash - docker compose logs -f - ``` - ## 🔧 Configuration ### Essential Environment Variables @@ -358,14 +254,16 @@ docker exec picpeak-backend cat data/ADMIN_CREDENTIALS.txt # Show current admin username and email (password is hidden) docker exec picpeak-backend node scripts/show-admin-credentials.js -# Reset the admin password to a new random password +# Reset the admin password to a new random password (displays new password in console) docker exec picpeak-backend node scripts/show-admin-credentials.js --reset ``` +> **Note:** When using `--reset`, the new password will be displayed in the console output. Save it immediately - it will not be shown again! + #### Important Security Notes - **Login requires the email address**, not username -- The admin password is only displayed once during initial setup +- When resetting password, the new password is displayed once in the console - save it immediately - **Password change is MANDATORY** on first login - the system will force you to change it - If you lose the password before first login, use the `--reset` option to generate a new one - New password requirements: minimum 12 characters, mixed case, numbers, and special characters diff --git a/SIMPLE_SETUP.md b/SIMPLE_SETUP.md index c5f80d74..b2b9ac56 100644 --- a/SIMPLE_SETUP.md +++ b/SIMPLE_SETUP.md @@ -451,6 +451,8 @@ cd /opt/picpeak/app/backend sudo -u picpeak node scripts/reset-admin-password.js ``` +> **Note:** The new password will be displayed in the console output and saved to `ADMIN_PASSWORD_RESET.txt`. Save it immediately! + ### Getting Help 1. **Check logs:** diff --git a/backend/scripts/show-admin-credentials.js b/backend/scripts/show-admin-credentials.js index 1215ff14..312b58b5 100644 --- a/backend/scripts/show-admin-credentials.js +++ b/backend/scripts/show-admin-credentials.js @@ -36,12 +36,14 @@ async function showAdminCredentials(resetPassword = false) { .where('id', admin.id) .update({ password_hash: passwordHash, + must_change_password: true, updated_at: new Date() }); - - // Password logging removed for security - check logs or database if needed - console.log('Password: [NEWLY RESET - stored in database]'); - console.log('\n⚠️ IMPORTANT: New password has been set in database!'); + + console.log(`Password: ${newPassword}`); + console.log('\n⚠️ IMPORTANT:'); + console.log('1. Save this password securely - it will not be shown again'); + console.log('2. You will be required to change it on next login'); } else { console.log('Password: [hidden - use --reset flag to generate new password]'); }