Skip to content

2.3.66 Satellite PhotoPrism

Jump to bottom
av edited this page Jan 6, 2026 · 2 revisions

PhotoPrism

Handle: photoprism URL: http://localhost:34691

Photoprism

photoprism is an AI-powered photo management app with face recognition, image classification (via TensorFlow), and automatic organization. It supports WebDAV sync, reverse geocoding, and has a beautiful web UI for browsing and organizing photos.

Starting

# [Optional] Pre-pull the images
harbor pull photoprism

# Start the service
harbor up photoprism

# [Optional] Open the web interface
harbor open photoprism

First Launch Notes:

  • Default Credentials: Log in with admin / harbor-photos. Change these for production deployments.
  • TensorFlow Download: On first startup, PhotoPrism downloads TensorFlow libraries (~400-500MB). This happens once and is cached in ./photoprism/storage/tensorflow/ for subsequent restarts.
  • NVIDIA GPU: If you have an NVIDIA GPU, Harbor automatically enables GPU acceleration for TensorFlow and video transcoding. You'll see tensorflow-gpu being installed in the logs.
  • Database Initialization: MariaDB initializes on first run. Wait for the healthcheck to pass before the main service becomes available.
  • Photo Library Mount: By default, PhotoPrism looks for photos in ~/Pictures. To use a different location, run harbor config set photoprism.originals /path/to/your/photos and restart the service.
  • Storage Volume: Thumbnails, cache, and sidecar files are stored in ./photoprism/storage/. This can grow significantly depending on your library size (plan ~1-2GB per 1000 photos).
  • Indexing Required: Photos are not visible until indexed. After adding photos, navigate to Library > Index and click Start.

Usage

You can interact with photoprism through its web interface. The app automatically indexes your photos and provides powerful organization and search features.

Key features:

  • AI-Powered Face Recognition - Automatically detects and groups faces in your photos
  • Image Classification - Uses TensorFlow for intelligent image categorization
  • Automatic Organization - Sort by date, location, and subjects
  • WebDAV Server - Sync photos from mobile devices
  • Interactive World Maps - Browse photos by location with Places
  • Albums & Moments - Create collections and view automatically generated moments
  • Smart Search - Find photos by content, color, faces, and more
  • RAW File Support - Work with professional camera formats
  • Video Transcoding - Play and organize video content
  • Multi-User Support - Share your library with family members

First-time Setup:

  1. Log in with default credentials
  2. Navigate to Library > Originals to start adding photos
  3. Click Start under Library > Index to begin indexing
  4. Explore Places, Moments, and Folders as indexing completes

Adding Photos:

  • Upload through the web interface
  • Mount your existing photo library to the originals folder
  • Use WebDAV to sync from mobile devices (Settings > Sync)

Explore more resources:

CLI Commands

Harbor exposes PhotoPrism CLI commands through the harbor photoprism subcommand:

# Get or set the vision model for Ollama integration
harbor photoprism model [model]

# List configured vision models
harbor photoprism vision ls

# Run caption generation on photos
harbor photoprism vision run -m caption

# Run label generation on photos
harbor photoprism vision run -m labels

# Test vision with debug output
harbor photoprism --log-level=trace vision run -m labels --count 1 --force

# Reset user password
harbor photoprism passwd admin

# List users
harbor photoprism users ls

For more CLI commands, see the PhotoPrism CLI documentation.

Configuration

Environment Variables

Following options can be set via harbor config:

# Main web UI port
HARBOR_PHOTOPRISM_HOST_PORT               34691

# MariaDB database port
HARBOR_PHOTOPRISM_MARIADB_HOST_PORT       34692

# Container images
HARBOR_PHOTOPRISM_IMAGE                   photoprism/photoprism
HARBOR_PHOTOPRISM_VERSION                 latest
HARBOR_PHOTOPRISM_MARIADB_IMAGE           mariadb
HARBOR_PHOTOPRISM_MARIADB_VERSION         11

# Admin credentials (⚠️ change for production!)
HARBOR_PHOTOPRISM_ADMIN_USER              admin
HARBOR_PHOTOPRISM_ADMIN_PASSWORD          harbor-photos

# Site settings
HARBOR_PHOTOPRISM_SITE_TITLE              PhotoPrism

# Storage paths
HARBOR_PHOTOPRISM_ORIGINALS               ~/Pictures
HARBOR_PHOTOPRISM_STORAGE                 ./photoprism/storage

# MariaDB database credentials
HARBOR_PHOTOPRISM_DB_NAME                 photoprism
HARBOR_PHOTOPRISM_DB_USER                 photoprism
HARBOR_PHOTOPRISM_DB_PASSWORD             sk-harbor-photoprism
HARBOR_PHOTOPRISM_DB_ROOT_PASSWORD        sk-harbor-photoprism-root

# Ollama vision model (used when running with Ollama)
HARBOR_PHOTOPRISM_VISION_MODEL            qwen3-vl:2b

Advanced Configuration

Additional settings can be configured using harbor env:

# Change admin password
harbor env photoprism PHOTOPRISM_ADMIN_PASSWORD your-secure-password

# Change site title
harbor env photoprism PHOTOPRISM_SITE_TITLE "My Photo Library"

# Disable TensorFlow (not recommended)
harbor env photoprism PHOTOPRISM_DISABLE_TENSORFLOW true

# Enable experimental features
harbor env photoprism PHOTOPRISM_EXPERIMENTAL true

Volumes

PhotoPrism uses two main storage directories:

  • ./photoprism/originals - Directory for original photos. Mount your existing photo library here or use this as the destination for uploads.
  • ./photoprism/storage - Storage for cache, thumbnails, database sidecars, and configuration files. Also contains the config/ folder for AI configuration.

To use an existing photo library:

# Set the originals path to your photo library
harbor config set photoprism.originals /path/to/your/photos
harbor restart photoprism

Ollama Integration

PhotoPrism supports Ollama for enhanced AI features including vision captions and labels. This allows you to use local LLMs for image analysis instead of cloud services.

Automatic Setup

When you run PhotoPrism together with Ollama, Harbor automatically configures the vision model integration:

# Start with Ollama integration
harbor up ollama photoprism

# Pull the default vision model
harbor ollama pull qwen3-vl:2b

# Restart to ensure config is loaded
harbor restart photoprism

The vision configuration is automatically generated from the template in photoprism/vision.yml.template using the HARBOR_PHOTOPRISM_VISION_MODEL setting.

Changing the Vision Model

To use a different vision model:

# Set your preferred vision model
harbor config set photoprism.vision.model gemma3:latest

# Pull the model
harbor pull gemma3:latest

# Restart to apply changes
harbor restart photoprism

Manual Setup

If you prefer full control over the vision configuration, create a custom vision.yml in the storage config folder:

# Create the config directory if it doesn't exist
mkdir -p ./photoprism/storage/config

# Create the vision configuration
cat > ./photoprism/storage/config/vision.yml << 'EOF'
Models:
- Type: labels
  Model: your-model:latest
  Engine: ollama
  Run: auto
  Service:
    Uri: http://ollama:11434/api/generate
- Type: caption
  Model: your-model:latest
  Engine: ollama
  Run: auto
  Service:
    Uri: http://ollama:11434/api/generate
EOF

harbor restart photoprism

Recommended Vision Models

  • qwen3-vl - Excellent balance of quality and speed (recommended)
  • gemma3 - Google's multimodal model
  • minicpm-v - Lightweight option for limited hardware

Re-indexing

After configuring Ollama, re-index your library to generate AI captions and labels:

  • Navigate to Library > Index
  • Click Start to begin indexing

For more details on Ollama integration, see the official documentation.

Security Notes

Critical for Production Deployments:

The default admin credentials (admin / harbor-photos) and database passwords are insecure defaults meant for local development only. You must change these values before deploying to production.

# Set a secure admin password
harbor config set photoprism.admin.password your-secure-password

# Set secure database passwords
harbor config set photoprism.db.password your-db-password
harbor config set photoprism.db.root.password your-db-root-password

# Restart to apply changes
harbor restart photoprism

System Requirements

  • Memory: PhotoPrism requires at least 4GB of swap space for indexing large RAW files and videos
  • Storage: Plan for additional storage for thumbnails and cache (approximately 1-2GB per 1000 photos)
  • Database: Uses MariaDB for optimal performance (SQLite is not recommended for large libraries)

Troubleshooting

Cannot log in:

  • Verify you're using the correct credentials (default: admin / harbor-photos)
  • Check if the password was changed via environment variables
  • Reset password: harbor exec photoprism photoprism passwd admin

Indexing is slow:

  • Ensure adequate swap space (4GB+ recommended)
  • Check CPU and memory usage with harbor logs photoprism
  • Consider disabling RAW conversion if not needed

Face recognition not working:

  • Ensure TensorFlow is enabled (default)
  • Check logs for TensorFlow errors: harbor logs photoprism
  • Re-index with face detection enabled

Database connection issues:

  • Ensure the MariaDB container is healthy: docker ps
  • Check logs: harbor logs photoprism-mariadb
  • Verify database credentials match between service and database

WebDAV sync not working:

  • Enable WebDAV in Settings > Sync
  • Use the internal URL for connections within Harbor network
  • Check firewall settings for external access

For more help, refer to:

Home | CLI Reference | Services | Adding New Service | Compatibility

Clone this wiki locally