Photosphere

Photosphere is a cross-platform application for managing your database of digital media files (photos and videos). I like to think of it as the spiritual successor to Picasa but with a UI more like modern Google Photos and backed by a Git-style database for immutable binary files, like photos and videos, that have editable metadata.

Important features:

• Local first so you own it and you control it.
• Open source so you can understand what it does with your files.
• Maintain data sovereignty: the storage and privacy of your files are under your control.
• Build a corruption resistant database of your digital media files.
• Backup your database and keep your backup updated.
• Bidirectional synchronization between databases on different devices.
• Detect and repair corrupt files.
• Securely encrypt files that you store in the cloud vendor of your choice.
• Use the GUI to search, view and edit your photos and videos.

Photosphere is a local-first application available as:

• A CLI tool (build and manage databases from the command line) - grab it from the releases page.
• A desktop application app for Windows, macOS, and Linux - grab it from the releases page.
• A mobile application (Android and iOS apps - COMING SOON).

Visit the Photosphere website to learn more.

Note: The self-hosted server option has been discontinued for now, but may be reinstated later if there's demand for it.

Contained herein are the code for Photosphere's:

• Desktop app
• Mobile apps
• CLI tool

Early development of Photosphere was covered in the book The Feedback-Driven Developer.

To get up and running, see the wiki:

• Installation - Desktop
• Installation - CLI
• Getting Started - Desktop
• Getting Started - CLI

Ingesting assets

You can ingest assets using either the desktop app or the CLI tool.

In the desktop app, use the Import page to drag and drop files or folders (it can unpack zip files for you), and they are added to your gallery automatically.

From the command line, use psi add to scan a directory and do bulk uploads (it can unpack zip files for you).

To move assets from Google Photos:

• Use Google Takeout to export all your assets to a series of large zip files.
• Then use psi add on the directory containing the zip files (it can unpack zip files for you).

Project layout

• photosphere/
  • apps/
    • bdb-cli - BSON database CLI tool (for testing and debugging)
    • cli - Main CLI tool (psi)
    • desktop - Electron desktop application
    • desktop-frontend - React UI for Electron app
    • dev-frontend - Development web frontend
    • dev-server - WebSocket development server
    • mk-cli - Merkle tree CLI tool (for testing and debugging)
  • packages/
    • api - Core API for database operations
    • bdb - BSON database implementation
    • config - Shared configuration values such as the application version
    • encryption - Encryption primitives (AES-256-CBC + RSA hybrid, key management, streaming)
    • fuzzy-match - Fuzzy string matching based on Levenshtein edit distance
    • lan-share - Local-network sharing of database configs and secrets between devices
    • merkle-tree - Merkle tree data structure
    • node-api - Node.js API for database operations
    • node-utils - Node.js utility functions
    • rest-api - REST API server (used by the desktop app to serve local photos)
    • serialization - Serialization utilities
    • storage - Storage abstraction layer
    • task-queue - Task queue system
    • tools - Tool management and media processing (ffmpeg, ffprobe, ImageMagick)
    • user-interface - Shared React UI components
    • utils - General utility functions
    • vault - Cross-platform secrets management with multiple vault backends
  • test - Data for testing.

Running Photosphere locally for development

Pre-reqs

You need Bun installed to run this code. Tested against Bun v1.3.10 on Ubuntu Linux, Windows 10/11 and MacOS.

Setup

First, clone a local copy of the code repository:

git clone git@github.com:ashleydavis/photosphere.git

Then install all dependencies at the root of the monorepo:

cd photosphere
bun install

Compile the project

THIS STEP IS OPTIONAL

You don't have to compile the project before doing a build. You only should do this step if you change the code and want to make sure the TypeScript code still compiles after your change.

bun run compile

Running tests

You can run tests for all packages and apps from the root of the monorepo:

Run all tests

bun run test

Run tests in watch mode

bun run test:watch

Run smoke tests for the Electron app

bun run test:electron

This will build the Electron app and run Playwright smoke tests.

Run a single unit test by name or pattern

bun run test -- <test-name-or-pattern>

Run CLI smoke tests

bun run test:cli

Run a single CLI smoke test by number or name

bun run test:cli -- <number-or-name>

Run encrypted CLI smoke tests

bun run test:cli:encrypted

Run tests using the shell script

Using the shell script doesn't run the tests in parallel and that makes it easier to see where a failure originates.

./run-tests.sh

This script runs all tests across the monorepo and provides a summary of results.

Run performance benchmarks

bun run perf

Building and running the Electron app

You can build and run the Electron desktop application directly from the root of the monorepo:

Development mode:

bun run dev

This will bundle the renderer process and start the Electron app in development mode with hot reload.

Production build:

bun run build

This will bundle the renderer process and build the Electron app for distribution.

Other instructions

To run the CLI tool, follow the instructions in ./apps/cli/README.md.

To start the dev-server, follow the instructions in ./apps/dev-server/README.md.

To start the dev-frontend, follow the instructions in ./apps/dev-frontend/README.md.