Getting Started - ashleydavis/photosphere GitHub Wiki

The Photosphere CLI (psi) is a command-line tool for managing your media file database.

Installation

Get the latest release from GitHub:

https://github.com/ashleydavis/photosphere/releases

Find the latest numbered version or if you are feeling lucky find the latest nightly build.

Download the appropriate tar or zip for your platform, unpack it and put the psi executable in your path:

Linux: psi
Windows: psi.exe
macOS: psi

Set permissions

Important: After downloading, make sure the binary has execute permissions:

# On Linux/macOS
chmod +x psi

# Verify permissions
ls -la psi

The binary should show execute permissions like -rwxr-xr-x for the user.

macOS Additional Step: If you encounter "cannot be opened because the developer cannot be verified" or similar security warnings, you need to remove the quarantine attributes that macOS adds to downloaded files:

# Remove quarantine attributes on macOS
xattr -c ./psi

This is required because macOS Gatekeeper automatically quarantines downloaded binaries that aren't code-signed by a registered Apple developer. The xattr -c command removes these extended attributes, allowing the binary to run normally. This is safe for trusted binaries like the Photosphere CLI.

Building from Source

You need to install Bun to build from source code.

# Clone the repository
git clone [email protected]:ashleydavis/photosphere.git
cd photosphere

# Install dependencies
bun install

# Build the CLI tool
cd apps/cli
bun run build-linux   # For Linux
bun run build-win     # For Windows
bun run build-mac     # For macOS

Quick Start

1. Initialize a Database

Create a new Photosphere database in your desired directory:

mkdir my-photos
cd my-photos
psi init

With encryption:

psi init --key ~/my-key --generate-key

2. Add Media Files

Add photos and videos to your database:

# Add individual files
psi add ~/Pictures/vacation.jpg ~/Videos/birthday.mp4

# Add entire directories
psi add ~/Pictures/2024/

3. View Database Summary

Check a summary of what's in your database:

psi summary

This shows total files, size, and database hash for verification.

4. List Database Contents

Browse the files in your database with interactive pagination:

psi list

This shows all files sorted by date (newest first) with their asset IDs, filenames, dimensions, and other metadata. Use Enter to see more files or Escape to exit. The asset IDs shown can be used with the export command.

5. Verify Database Integrity

Check that your files haven't been corrupted or modified:

psi verify

This compares file lengths, modification times and ultimately file hashes to detect any changes since the files were added.

6. Create a Backup

Replicate your database to create a backup:

psi replicate --dest ~/backup/my-photos

This creates an exact copy that can be used for backup or migration.

7. Compare Databases

Verify that your backup matches the original:

psi compare --dest ~/backup/my-photos

This uses the merkle tree to quickly identify any differences between databases.

8. Repair Database Issues

If files become corrupted or missing, you can repair them from a backup database:

# Repair corrupted files from a backup
psi repair --source ~/backup/my-photos

# Force full verification and repair
psi repair --source ~/backup/my-photos --full

The repair command will:

Compare files between your database and the source backup
Restore any missing files from the backup
Replace corrupted files with clean versions from the backup
Verify file integrity after repair

Important: Always create regular backups with psi replicate so you have a clean source to repair from.

9. Launch the Web UI

View and manage your media through a local version of the web interface:

psi ui

The UI will automatically open in your default browser. Use --no-open to prevent auto-opening.

10. Export Specific Assets

Export individual assets from your database by their unique ID:

# Export original file
psi export abc123-def4-5678-9012-345678901234 ./exported-photo.jpg

# Export to directory (keeps original filename)  
psi export abc123-def4-5678-9012-345678901234 ./exports/

# Export web-optimized display version
psi export abc123-def4-5678-9012-345678901234 ./output.jpg --type display

# Export thumbnail version
psi export abc123-def4-5678-9012-345678901234 ./thumbs/ --type thumb

Finding Asset IDs: Asset IDs can be found through the web UI when viewing asset details, or using psi list.

Database Structure

Photosphere organizes your media into:

Original files: Full resolution originals
Display versions: Web-optimized versions
Thumbnails: Small preview images
Metadata: EXIF data, timestamps, and custom tags

The database directory structure:

my-photos/
├── .db/           # Database metadata
├── assets/        # Original media files
├── display/       # Optimized versions
├── thumb/         # Thumbnails
└── metadata/      # BSON metadata for media files.

Encryption

To protect your media with encryption:

Generate a key on first init:
```
psi init --key ~/my-key --generate-key
```

Use the same key for all operations:

psi add ~/new-photos/ --key ~/my-key.pem
psi ui --key ~/my-key.pem
psi export abc123-def4-5678-9012-345678901234 ./output.jpg --key ~/my-key.pem

Encrypt on replication:

psi replicate --key ~/my-key --generate-key --dest s3:my-bucket/my-photos

If you use encryption please don't lose your encryption key. If you lose it you lose access to your encrypted database.

My advice: As soon as you generate a key store it safely in your password manager.

Cloud Storage (S3)

Photosphere supports S3-compatible storage for both local and cloud deployments. You can use AWS S3, DigitalOcean Spaces, MinIO, or any S3-compatible service.

For detailed instructions on setting up Digital Ocean Spaces, see Configuration-Digital-Ocean-Spaces.

Configuring S3 Credentials

Use the config command to set up your AWS credentials and set your Google API key for reverse geocoding:

# Configure credentials
psi config

You can also set AWS credentials using environment variables:

export AWS_ACCESS_KEY_ID=<your-access-key-id>
export AWS_SECRET_ACCESS_KEY=<your-secret-key>
export AWS_DEFAULT_REGION=us-east-1 # Set this to us-east-1 for Digital Ocean.
export AWS_ENDPOINT=https://syd1.digitaloceanspaces.com # If using Digital Ocean, replace with the endpoint for your DO data center.

Authentication Setup

When running Photosphere as a server, you can configure Auth0 for user authentication. For detailed instructions on setting up Auth0 and configuring the necessary environment variables, see Configuration-Auth0.

Using S3 Storage

Once configured, you can use S3 paths directly in commands:

# Replicate a local database to S3
psi replicate --db my-photos --dest s3:my-bucket/photos

# Initialize an empty database in S3
psi init --db s3:my-bucket/photos

# Add files to S3-backed database
psi add --db s3:my-bucket/photos ~/Pictures/*.jpg

# Launch UI for S3 database
psi ui --db s3:my-bucket/photos

Clearing Configuration

To remove all configuration files:

psi config --clear

This will prompt for confirmation before deleting all credential files.