Perkeep

Key Features

• Content-addressed storage using cryptographic hashes for immutable, deduplication-friendly blob storage
• Schema-based metadata system that preserves rich context about files, locations, people, and events
• Multi-source import capabilities including Google Photos, Twitter archives, Pinboard bookmarks, and filesystem scanning
• Command-line tools (pk) for batch operations like putting files, syncing repositories, and complex searches
• Web-based interface for browsing, searching, and organizing personal content with timeline views
• Automatic EXIF parsing and GPS location extraction from photos with map integration
• Immutable append-only storage that preserves complete history without ever losing previous versions
• Built-in replication and backup capabilities for distributing blobs across multiple storage backends

Common Use Cases

• 1Personal digital archiving for photographers who want permanent storage of RAW files with full metadata preservation
• 2Lifelogging enthusiasts collecting and correlating data from multiple social media platforms and services
• 3Digital estate planning where families need long-term, searchable archives of personal content and communications
• 4Research projects requiring immutable storage of documents, images, and data with full provenance tracking
• 5Privacy-focused individuals migrating away from Google Photos or iCloud while maintaining search capabilities
• 6Content creators building searchable archives of work spanning multiple platforms and decades
• 7Digital nomads centralizing photos, documents, and memories from various devices and cloud services

Prerequisites

• Minimum 2GB RAM recommended for blob indexing and search operations on large collections
• Port 3179 available for Perkeep web interface access
• Strong password set in PERKEEP_PASSWORD environment variable for admin authentication
• Understanding of content-addressed storage concepts and immutable blob architecture
• Sufficient disk space planning as Perkeep stores everything permanently without deletion
• Basic familiarity with command-line tools if planning to use pk utilities for bulk operations

docker-compose.yml

1services: 
2  perkeep: 
3    image: bradfitz/perkeep:latest
4    container_name: perkeep
5    restart: unless-stopped
6    environment: 
7      CAMLI_AUTH: userpass:admin:${PERKEEP_PASSWORD}
8    volumes: 
9      - perkeep_data:/srv/perkeep
10    ports: 
11      - "3179:3179"
12
13volumes: 
14  perkeep_data: 

.env Template

1PERKEEP_PASSWORD=changeme

Usage Notes

Quick Start

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  perkeep:
5    image: bradfitz/perkeep:latest
6    container_name: perkeep
7    restart: unless-stopped
8    environment:
9      CAMLI_AUTH: userpass:admin:${PERKEEP_PASSWORD}
10    volumes:
11      - perkeep_data:/srv/perkeep
12    ports:
13      - "3179:3179"
14
15volumes:
16  perkeep_data:
17EOF
18
19# 2. Create the .env file
20cat > .env << 'EOF'
21PERKEEP_PASSWORD=changeme
22EOF
23
24# 3. Start the services
25docker compose up -d
26
27# 4. View logs
28docker compose logs -f

One-Liner

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

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

Troubleshooting