How to Deploy & Use photoprism

# PhotoPrism Deployment & Usage Guide

## 1. Prerequisites

### Minimum Requirements
- **Docker** (recommended) or **Docker Compose** for containerized deployment
- **64-bit** AMD/Intel or ARM processor (Raspberry Pi, Apple Silicon supported)
- **4 GB RAM** minimum (8+ GB recommended for AI features)
- **Storage**: 2x the size of your photo library for thumbnails and backups
- **Web browser** for accessing the web interface

### Optional (for development/build from source)
- **Go 1.21+** (for backend compilation)
- **Node.js 18+** and **npm** (for frontend build)
- **Git** (for cloning repository)
- **ffmpeg** (video transcoding support)
- **ImageMagick** (advanced image processing)

---

## 2. Installation

### Option A: Docker (Recommended)

#### Quick Start with Docker Compose
1. Create a `docker-compose.yml` file:
```yaml
version: '3.8'
services:
  photoprism:
    image: photoprism/photoprism:latest
    depends_on:
      - mariadb
    ports:
      - "2342:80"
    environment:
      PHOTOPRISM_UPLOAD_NSFW: "true" # optional
      PHOTOPRISM_DATABASE_DRIVER: "mysql"
      PHOTOPRISM_DATABASE_SERVER: "mariadb:3306"
      PHOTOPRISM_DATABASE_NAME: "photoprism"
      PHOTOPRISM_DATABASE_USER: "photoprism"
      PHOTOPRISM_DATABASE_PASSWORD: "photoprism"
    volumes:
      - ./photos:/photoprism/storage/photos
      - ./import:/photoprism/storage/import
      - ./backups:/photoprism/storage/backups
    restart: unless-stopped

  mariadb:
    image: mariadb:10.11
    command: --transaction-isolation=READ-COMMITTED --log-bin=binlog --binlog-format=ROW
    volumes:
      - ./database:/var/lib/mysql
    environment:
      MARIADB_ROOT_PASSWORD: "photoprism"
      MARIADB_DATABASE: "photoprism"
      MARIADB_USER: "photoprism"
      MARIADB_PASSWORD: "photoprism"
    restart: unless-stopped

2. Start services:

docker-compose up -d

3. Access at http://localhost:2342

Single Container (for testing)

docker run -d \
  --name photoprism \
  -p 2342:80 \
  -v ~/photoprism/storage:/photoprism/storage \
  -e PHOTOPRISM_ADMIN_PASSWORD="yourpassword" \
  photoprism/photoprism:latest

Option B: Native Installation (Linux/macOS)

Using tar.gz Package

1. Download the latest package from dl.photoprism.app
2. Extract and install:

tar -xzf photoprism-linux-amd64.tar.gz
sudo mv photoprism /usr/local/bin/
sudo chmod +x /usr/local/bin/photoprism

3. Initialize storage:

photoprism init

4. Start the service:

photoprism start

Option C: Build from Source

1. Clone repository:

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

2. Build backend:

make build

3. Build frontend (if needed):

make assets

4. Install:

sudo cp photoprism /usr/local/bin/

3. Configuration

Environment Variables (Docker/CLI)

Configuration File

Create config.yml in storage directory (optional):

App:
  SiteUrl: "https://photos.example.com"
  UploadNsfw: true
  LogLevel: "info"

Database:
  Driver: "mysql"
  Server: "localhost:3306"
  Name: "photoprism"
  User: "photoprism"
  Password: "securepassword"

Storage:
  Path: "/photoprism/storage"
  ImportPath: "/photoprism/import"

4. Build & Run

Development (from source)

# Build with live reload
make dev

# Run tests
make test

# Build for production
make build

# Build Docker image
make docker

Production (Docker)

# Pull latest image
docker pull photoprism/photoprism:latest

# Run with custom storage
docker run -d \
  --name photoprism \
  -p 2342:80 \
  -v /path/to/photos:/photoprism/storage/photos \
  -v /path/to/backups:/photoprism/storage/backups \
  -e PHOTOPRISM_ADMIN_PASSWORD="yourpassword" \
  photoprism/photoprism:latest

Native Binary

# Initialize storage (first run only)
photoprism init

# Start server
photoprism start

# View logs
photoprism logs

# Stop server
photoprism stop

5. Deployment

Recommended Platforms

1. Docker Compose on VPS (Simplest)

• Deploy on any VPS (DigitalOcean, Linode, AWS EC2)
• Use docker-compose with Nginx reverse proxy
• Add SSL with Let's Encrypt (certbot)

2. Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: photoprism
spec:
  replicas: 1
  selector:
    matchLabels:
      app: photoprism
  template:
    metadata:
      labels:
        app: photoprism
    spec:
      containers:
      - name: photoprism
        image: photoprism/photoprism:latest
        ports:
        - containerPort: 80
        env:
        - name: PHOTOPRISM_STORAGE_PATH
          value: "/storage"
        volumeMounts:
        - name: storage
          mountPath: "/storage"
      volumes:
      - name: storage
        persistentVolumeClaim:
          claimName: photoprism-pvc

3. Synology/QNAP NAS

• Use Docker package in Package Center
• Create shared folders for storage/photos, storage/backups
• Configure container volumes accordingly

4. Raspberry Pi/ARM

# Use ARM-specific image
docker run -d \
  --name photoprism \
  --platform linux/arm/v7 \
  -p 2342:80 \
  -v ~/photoprism:/photoprism/storage \
  photoprism/photoprism:arm

Reverse Proxy Setup (Nginx)

server {
    listen 80;
    server_name photos.example.com;
    
    location / {
        proxy_pass http://localhost:2342;
        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;
    }
}

6. Troubleshooting

Common Issues

1. Database Connection Failed

# Check database container logs
docker-compose logs mariadb

# Verify credentials in environment variables
docker exec photoprism env | grep DATABASE

# Test connection from photoprism container
docker exec photoprism mysql -h mariadb -u photoprism -p

2. Storage Permission Errors

# Fix permissions (Docker)
sudo chown -R 1000:1000 ~/photoprism/storage

# For native install
sudo chown -R photoprism:photoprism /var/lib/photoprism

3. Photos Not Indexing

• Check import folder permissions
• Verify file formats supported (JPEG, PNG, HEIC, RAW, MP4, etc.)
• Run manual index: photoprism index --cleanup
• Check logs: photoprism logs or docker logs photoprism

4. Memory/CPU Issues

• Limit concurrent indexing: PHOTOPRISM_WORKERS=2
• Disable AI features: PHOTOPRISM_DISABLE_TENSORFLOW=1
• Increase Docker memory limit (default 2GB)

5. Reverse Proxy 502 Errors

• Verify proxy_pass URL matches container port
• Check that PhotoPrism is running: docker ps
• Ensure no firewall blocking port 2342

6. Face Recognition Not Working

• Ensure TensorFlow dependencies installed (Docker image includes them)
• Check logs for "tensorflow" errors
• Verify at least 5+ face images per person for training
• Run: photoprism faces --search

Log Locations

• Docker: docker logs photoprism
• Native: /var/lib/photoprism/storage/logs/
• Systemd: journalctl -u photoprism

Reset Admin Password

# Docker
docker exec photoprism photoprism passwd admin

# Native
photoprism passwd admin

Database Backup

# Docker
docker exec mariadb mysqldump -u photoprism -pphotoprism photoprism > backup.sql

# Native
mysqldump -u photoprism -p photoprism > backup.sql

Performance Tips

1. Use SSD storage for database and thumbnails
2. Set PHOTOPRISM_WORKERS to CPU core count (default: auto-detect)
3. Exclude large folders from indexing via .photoprism ignore file
4. Schedule indexing during off-peak hours with PHOTOPRISM_INDEX_INTERVAL

Need Help?

• Documentation: https://docs.photoprism.app/
• Community Chat: https://link.photoprism.app/chat
• GitHub Issues: https://github.com/photoprism/photoprism/issues