### [PhotoPrism](https://github.com/photoprism/photoprism)

> Handle: `photoprism`
> URL: [http://localhost:34691](http://localhost:34691)

![Photoprism](./harbor-photoprism.png)

`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

```bash
# [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:
- [Official Documentation](https://docs.photoprism.app/)
- [User Guide](https://docs.photoprism.app/user-guide/)

#### CLI Commands

Harbor exposes PhotoPrism CLI commands through the `harbor photoprism` subcommand:

```bash
# 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](https://docs.photoprism.app/user-guide/ai/cli/).

#### Configuration

##### Environment Variables

Following options can be set via [`harbor config`](./3.-Harbor-CLI-Reference.md#harbor-config):

```bash
# 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`](./3.-Harbor-CLI-Reference.md#harbor-env):

```bash
# 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:

```bash
# 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:

```bash
# 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 `services/photoprism/vision.yml.template` using the `HARBOR_PHOTOPRISM_VISION_MODEL` setting.

##### Changing the Vision Model

To use a different vision model:

```bash
# 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:

```bash
# 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](https://docs.photoprism.app/user-guide/ai/using-ollama/).

#### 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.

```bash
# 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-db`
- 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:
- [Official Troubleshooting Guide](https://docs.photoprism.app/getting-started/troubleshooting/)
- [Community Forum](https://community.photoprism.app/)
- [GitHub Issues](https://github.com/photoprism/photoprism/issues)
