PhotoStructure

beginner

Photo and video organization tool.

Overview

PhotoStructure is an intelligent photo and video organization tool created by Matthew McEachen that automatically organizes your entire media collection using metadata analysis, computer vision, and machine learning. Unlike traditional photo galleries that rely on folder structures, PhotoStructure analyzes EXIF data, timestamps, GPS coordinates, and visual content to create a comprehensive timeline and browsing experience that reveals your photos in new ways. The application builds a sophisticated database that indexes your media without modifying original files, making it safe to point at existing photo collections. This Docker deployment runs PhotoStructure Server in a containerized environment with carefully configured volume mounts that separate your original photos from PhotoStructure's organizational database. The setup mounts your photo directories as read-only to ensure complete safety of original files, while PhotoStructure's library and configuration data are stored in dedicated Docker volumes. The application performs deep analysis of your media collection, extracting technical metadata, detecting faces and objects, and organizing content by date, location, camera equipment, and identified people. This stack is ideal for photography enthusiasts, families with large photo collections, and anyone struggling to manage years of accumulated digital media across multiple devices and storage locations. PhotoStructure excels at handling mixed collections from different cameras, phones, and time periods, making it particularly valuable for users consolidating photos from various sources or those who want intelligent organization without manual tagging and folder management.

Key Features

Automatic chronological organization using EXIF timestamps and file modification dates
GPS metadata extraction for location-based browsing and mapping of photo locations
Duplicate detection and management across different file formats and resolutions
Face detection and grouping for people-based photo organization
Camera and lens identification with equipment-based filtering and browsing
Raw image format support with thumbnail generation for professional photography workflows
Safe read-only mounting that never modifies original photo files
Progressive scanning that allows browsing while initial organization continues in background

Common Use Cases

1Photography enthusiasts organizing collections from multiple cameras and lenses
2Families consolidating photos from various family members' devices and cloud accounts
3Digital archivists preserving and organizing historical photo collections
4Content creators managing large libraries of stock photos and reference images
5Home users replacing cloud photo services with self-hosted organization
6Professional photographers organizing client sessions and portfolio work
7Anyone migrating from proprietary photo management software to open solutions

Prerequisites

Minimum 4GB RAM recommended for processing large photo collections
Sufficient disk space for PhotoStructure's database (typically 1-5% of original photo collection size)
Port 1787 available for PhotoStructure web interface access
Read access to photo directories you want to organize
Docker Compose v2.0 or higher with volume support
Basic understanding of file permissions for mounting photo directories

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  photostructure: 
3    image: photostructure/server:stable
4    container_name: photostructure
5    restart: unless-stopped
6    environment: 
7      PS_LOG_LEVEL: info
8    volumes: 
9      - photostructure_config:/ps/config
10      - photostructure_library:/ps/library
11      - /path/to/photos:/ps/photos:ro
12    ports: 
13      - "1787:1787"
14
15volumes: 
16  photostructure_config: 
17  photostructure_library:

.env Template

.env

1# Mount your photos folder

Usage Notes

1Docs: https://photostructure.com/getting-started/
2Access at http://localhost:1787
3Mount photos read-only to /ps/photos - original files untouched
4Library stored in /ps/library - this is PhotoStructure's database
5Auto-organizes by date/location/camera/people
6Initial scan takes time - check progress in web UI

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  photostructure:
5    image: photostructure/server:stable
6    container_name: photostructure
7    restart: unless-stopped
8    environment:
9      PS_LOG_LEVEL: info
10    volumes:
11      - photostructure_config:/ps/config
12      - photostructure_library:/ps/library
13      - /path/to/photos:/ps/photos:ro
14    ports:
15      - "1787:1787"
16
17volumes:
18  photostructure_config:
19  photostructure_library:
20EOF
21
22# 2. Create the .env file
23cat > .env << 'EOF'
24# Mount your photos folder
25EOF
26
27# 3. Start the services
28docker compose up -d
29
30# 4. View logs
31docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/photostructure/run | bash

Troubleshooting

Library rebuild taking too long: Adjust PS_LOG_LEVEL to debug and monitor scanning progress, consider excluding very large directories initially
Photos not appearing in timeline: Verify read permissions on mounted photo directories and check that PS_LOG_LEVEL shows scanning activity
High CPU usage during scanning: Normal behavior during initial indexing, but can limit concurrent scanning threads via PhotoStructure settings
Duplicate photos showing incorrectly: PhotoStructure's duplicate detection may need manual review for similar but distinct images
Web interface not accessible: Ensure port 1787 isn't blocked by firewall and container started successfully with docker-compose logs photostructure
Missing GPS location data: Some photos may lack GPS EXIF data, PhotoStructure can only organize by location when this metadata exists

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

photostructure

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download