Full PhotoPrism Setup Guide on Raspberry Pi (or Linux Server)

Complete Guide: Setting Up PhotoPrism on Raspberry Pi with External Drive

1. Prepare Your Raspberry Pi

• Use Raspberry Pi 4 (2GB+ RAM) or similar Linux device
• Install Raspberry Pi OS (64-bit recommended) and update system:

sudo apt update && sudo apt upgrade -y

• Ensure internet connection and SSH access if remote

2. Install Docker

1. Download and install Docker with the official script:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

3. Add your user to the docker group (replace pi with your username):

sudo usermod -aG docker pi

5. Log out and back in or reboot for group changes to apply
6. Verify Docker installation:

docker --version

3. Install Docker Compose Plugin

• Download and install the Docker Compose plugin for ARM64:

sudo mkdir -p /usr/lib/docker/cli-plugins/
sudo curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-aarch64 -o /usr/lib/docker/cli-plugins/docker-compose
sudo chmod +x /usr/lib/docker/cli-plugins/docker-compose

• Verify installation:

docker compose version

4. Mount and Prepare External Hard Drive

• Connect your external SSD/HDD to the Raspberry Pi
• Identify mount point (example: /media/pi/myssd) or mount manually
• To auto-mount on boot, edit /etc/fstab accordingly (optional)
• Create folders for PhotoPrism data on the mounted drive:

mkdir -p /media/pi/myssd/photoprism/originals
mkdir -p /media/pi/myssd/photoprism/storage

• Set permissions for Docker to access:

sudo chown -R pi:pi /media/pi/myssd/photoprism
sudo chmod -R 755 /media/pi/myssd/photoprism

5. Create Docker Compose Configuration

• Create and edit docker-compose.yml in a directory, e.g. ~/photoprism/:

nano ~/photoprism/docker-compose.yml

• Paste this configuration (update password and paths accordingly):

version: "3.8"

services:
  photoprism:
    image: photoprism/photoprism:latest
    container_name: photoprism
    restart: unless-stopped
    ports:
      - "2342:2342"
    environment:
      PHOTOPRISM_ADMIN_PASSWORD: "yourpassword"
      PHOTOPRISM_SITE_URL: "http://localhost:2342/"
      PHOTOPRISM_ORIGINALS_LIMIT: 500000
      PHOTOPRISM_DISABLE_TLS: "true"
    volumes:
      - /media/pi/myssd/photoprism/originals:/photoprism/originals
      - /media/pi/myssd/photoprism/storage:/photoprism/storage

6. Start PhotoPrism

• Navigate to your compose folder and launch PhotoPrism container:

cd ~/photoprism
docker compose up -d

• Check running containers:

docker ps

7. Access PhotoPrism Web Interface

• Find your Raspberry Pi’s local IP address:

hostname -I

• On any device connected to the same network (phone, PC), open a browser and visit:

http://<Raspberry_Pi_IP>:2342

• Log in with username admin and the password you set

8. Configure PhotoPrism to Start Automatically on Boot

• Create a systemd service file:

sudo nano /etc/systemd/system/photoprism.service

• Paste the following:

[Unit]
Description=PhotoPrism Container
Requires=docker.service
After=docker.service

[Service]
Restart=always
WorkingDirectory=/home/pi/photoprism
ExecStart=/usr/bin/docker compose up
ExecStop=/usr/bin/docker compose down
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target

• Enable and start the service:

sudo systemctl enable photoprism.service
sudo systemctl start photoprism.service

• Check status:

sudo systemctl status photoprism.service

9. Upload and Index Your Photos

• Copy photos to /media/pi/myssd/photoprism/originals via USB, SCP, SMB, or other methods
• In the PhotoPrism web UI, go to Library → Index to scan and process the photos

10. Optional: Remote Access Setup

• Set up port forwarding on your router: forward external port (e.g., 2342) to Raspberry Pi’s port 2342
• Use Dynamic DNS services if your external IP changes frequently
• For security, use a VPN or tools like Tailscale to access remotely without exposing ports publicly

Additional Tips

• Ensure your firewall on Raspberry Pi and router allows traffic on port 2342
• Backup your PhotoPrism storage folder regularly (/media/pi/myssd/photoprism/storage)
• Adjust PhotoPrism settings via its web interface for indexing intervals, user management, and performance