Codakey
Play
← Back to photoview

How to Deploy & Use photoview

Photoview Deployment and Usage Guide

1. Prerequisites

Required Software

  • Docker Engine (released within the last year, major version not older than previous one)
  • Docker Compose (for containerized deployment)
  • Node.js (for local development only)
  • PostgreSQL 18 (or PostgreSQL 17 for compatibility)
  • Git (for cloning the repository)

Hardware Requirements

  • Sufficient storage for your photo/video collection
  • Adequate RAM for image processing (minimum 2GB recommended)
  • CPU with hardware acceleration support (optional, for video transcoding)

Accounts

  • Docker Hub account (optional, for custom image management)
  • PostgreSQL database (can be self-hosted or managed service)

2. Installation

Docker Installation (Recommended)

  1. Clone the repository:

    git clone https://github.com/photoview/photoview.git
cd photoview

  2. Copy the example Docker Compose configuration:

    cp docker-compose\ example/docker-compose.example.yml docker-compose.yml

  3. Update the docker-compose.yml file:

    • Change the image registry from viktorstrate/photoview to photoview/photoview
    • Configure volume mounts for your media directories
    • Set PostgreSQL 18 as the database version

Manual Installation

  1. Install dependencies:

    # Install UI dependencies
cd ui
npm install

# Install API dependencies
cd ../api
npm install

  2. Build the project:

    # Build UI
cd ui
npm run build

# Build API
cd ../api
npm run build

3. Configuration

Environment Variables

Create a .env file in the project root with the following variables:

# Database Configuration
DATABASE_TYPE=postgres
POSTGRES_USER=photoview
POSTGRES_PASSWORD=your_secure_password
POSTGRES_DB=photoview
POSTGRES_HOST=localhost
POSTGRES_PORT=5432

# Application Configuration
PHOTOVIEW_LISTEN_IP=0.0.0.0
PHOTOVIEW_LISTEN_PORT=80
PHOTOVIEW_MEDIA_CACHE=/app/cache
PHOTOVIEW_SERVE_UI=true

# Authentication
PHOTOVIEW_INITIAL_ADMIN_USERNAME=admin
PHOTOVIEW_INITIAL_ADMIN_PASSWORD=your_admin_password

# Media Paths
PHOTOVIEW_MEDIA_PATH=/path/to/your/photos

Docker Compose Configuration

Key configuration sections in docker-compose.yml:

services:
  photoview:
    image: photoview/photoview:latest
    container_name: photoview
    restart: unless-stopped
    ports:
      - "80:80"
    volumes:
      - ./photos:/photos:ro
      - ./cache:/app/cache
    environment:
      - DATABASE_TYPE=postgres
      - POSTGRES_HOST=postgres
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DB}
      - PHOTOVIEW_MEDIA_PATH=/photos
      - PHOTOVIEW_MEDIA_CACHE=/app/cache
    depends_on:
      - postgres

  postgres:
    image: postgres:18-alpine
    container_name: photoview-postgres
    restart: unless-stopped
    volumes:
      - postgres_data:/var/lib/postgresql
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DB}

volumes:
  postgres_data:

Important Notes

  • Database Volume Mount: For PostgreSQL 18+, the database is mounted to /var/lib/postgresql (previously /var/lib/postgresql/data)
  • Media Paths: Ensure your media directories are correctly mounted in Docker volumes
  • Cache Directory: Configure a persistent cache directory for thumbnails and optimized media

4. Build & Run

Development Environment

  1. Set up local development:

    # Install all dependencies
npm install

# Start API server (development mode)
cd api
npm run dev

# In another terminal, start UI server
cd ui
npm run dev

  2. Access the application:

    • API: http://localhost:4001
    • UI: http://localhost:3000
    • GraphQL endpoint: http://localhost:4001/api/graphql

Production Build

  1. Build the application:

    # Build both UI and API
npm run build

  2. Run with Docker Compose:

    docker-compose up -d

  3. Access the application at http://localhost:80

Hardware Acceleration (Optional)

For video transcoding acceleration, add the following to your Docker Compose:

photoview:
  # ... existing configuration
  devices:
    - /dev/dri:/dev/dri
  environment:
    - PHOTOVIEW_VIDEO_CODEC=vaapi

5. Deployment

Docker-Based Deployment Platforms

  1. Self-Hosted Server (Recommended)

    • Ubuntu/Debian with Docker Engine
    • Use Docker Compose for orchestration
    • Set up reverse proxy (Nginx/Traefik) for SSL termination

  2. Cloud Platforms

    • AWS: ECS with Fargate or EC2 with Docker
    • Google Cloud: Cloud Run or GKE
    • Azure: Container Instances or AKS
    • DigitalOcean: Docker on Droplets or App Platform

  3. NAS Devices

    • Synology DSM with Docker Package
    • QNAP Container Station
    • TrueNAS Scale with Docker support

Deployment Steps

  1. Prepare Infrastructure:

    • Set up PostgreSQL 18 database
    • Configure persistent storage for media and cache
    • Set up network and firewall rules

  2. Deploy with Docker:

    # Pull latest image
docker pull photoview/photoview:latest

# Deploy with Docker Compose
docker-compose up -d

  3. Configure Reverse Proxy (Example Nginx):

    server {
    listen 443 ssl http2;
    server_name photos.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:80;
        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;
    }
}

  4. Initial Setup:

    • Access the web interface
    • Log in with initial admin credentials
    • Configure user paths and permissions
    • Start media scanning

6. Troubleshooting

Common Issues

Database Connection Issues

Problem: Photoview cannot connect to PostgreSQL Solution:

# Check if PostgreSQL is running
docker ps | grep postgres

# Check logs
docker logs photoview-postgres

# Verify environment variables
docker exec photoview env | grep POSTGRES

Media Scanning Not Working

Problem: Photos don't appear after scanning Solution:

  1. Check volume mounts are correct: 
    docker inspect photoview | grep Mounts
  2. Verify file permissions: 
    docker exec photoview ls -la /photos
  3. Check scanner logs: 
    docker logs photoview | grep -i scan

PostgreSQL 18 Upgrade Issues

Problem: Database not starting after upgrade Solution:

  1. Backup your database before upgrading
  2. Follow PostgreSQL official upgrade guide
  3. Update volume mount from /var/lib/postgresql/data to /var/lib/postgresql
  4. Run database migration if needed

WebSocket Connection Errors

Problem: GraphQL subscriptions not working Solution:

  1. Check GraphQL endpoint configuration in ui/src/apolloClient.ts: 
    export const API_ENDPOINT = import.meta.env.REACT_APP_API_ENDPOINT
  ? (import.meta.env.REACT_APP_API_ENDPOINT as string)
  : urlJoin(location.origin, '/api')
  2. Verify WebSocket protocol matches your deployment: 
    const apiProtocol = new URL(GRAPHQL_ENDPOINT).protocol
const websocketUri = new URL(GRAPHQL_ENDPOINT)
websocketUri.protocol = apiProtocol === 'https:' ? 'wss:' : 'ws:'

Performance Issues

Problem: Slow thumbnail generation or video transcoding Solution:

  1. Increase cache size in configuration
  2. Enable hardware acceleration if available
  3. Adjust scanner concurrency settings
  4. Monitor system resources during scanning

Authentication Problems

Problem: Cannot log in or session expires Solution:

  1. Clear browser cookies and cache
  2. Verify authentication token handling in ui/src/helpers/authentication.ts
  3. Check CORS configuration if using reverse proxy
  4. Ensure secure cookies are properly configured for HTTPS

Logs and Diagnostics

# View Photoview logs
docker logs photoview -f

# View PostgreSQL logs
docker logs photoview-postgres -f

# Check container health
docker ps --filter "name=photoview"

# Monitor resource usage
docker stats photoview photoview-postgres

Getting Help

← Project overviewView alternatives to photoview →