PiGallery2 Documentation

PiGallery2 is a fast, directory-first photo gallery website designed to run on low-resource servers.

Key characteristics:

• Fast: Optimized for low-end hardware (e.g., Raspberry Pi).
• Simple: Configuration is minimal; point the application to your photo directory to begin.
• Directory-first: The UI reflects your existing folder structure.
• Read-only: The application does not modify your original photo files.

The benchmark/README.md file contains historical performance data for PiGallery2. These benchmarks provide insight into how different operations (scanning, listing, searching, and face listing) perform on specific hardware configurations.

Note that these are historical records and may not reflect the performance of the current version or your specific hardware setup.

The backend is located in src/backend/ and follows this organization:

• middlewares/: Input validation and transformation.
• model/: Business logic, further divided into:
  • database/: Data retrieval (includes sql/ for SQL databases and memory/ for memory-based logic).
  • interfaces/: Database-independent interfaces.
• diagnostics/: Startup checks (settings validation, package availability, etc.).
• fileprocessing/: Photo and video conversion logic.
• jobs/: Job scheduling (crontab-like features).
• threading/: Code running on separate threads (e.g., DiskManagerWorker.ts for directory scanning, Metadataloader.ts for metadata parsing).
• routers/: HTTP API endpoint declarations.
• index.ts & server.ts: Server startup and HTTP server configuration.
• ProjectPath.ts: A singleton containing project-related paths.

You can place specific .pg2conf files within your gallery directories to customize how PiGallery2 handles that specific directory. These files control sorting, upload permissions, and saved searches.

Note that some files are processed on the Client side (affecting how the UI displays the directory), while others are processed on the Server side (affecting how the directory is indexed or managed).

The repository is organized into several key directories:

Root Structure

• src/: The primary source code directory.
• test/: Unit and integration tests.
• docker/: Docker configurations (recommended for deployment).
• docs/: Project documentation.

Source Structure (src/)

• backend/: Node.js backend code.
• frontend/: Angular-based frontend.
• common/: Shared files (primarily DTOs) used by both frontend and backend.

PiGallery2 operates on a philosophy where the disk is the source of truth and the database is only a cache. The application is designed to reflect your photo organization exactly as it exists on your storage.

Because the database is a cache, it can be deleted and rebuilt at any time without losing your photo organization. This design choice ensures portability and ease of rebuilding, but it means that traditional database-only albums are replaced by Logical Albums (saved search queries) to maintain the directory-first approach.

To associate specific sections of an index.md file with a specific date, use the @pg-date HTML comment tag.

When you use the 'group by date' feature in the gallery, the content tagged with a specific date will be moved from the main markdown view and displayed only under that assigned day.

Format: <!-- @pg-date <ISO_DATE> -->

<!-- @pg-date 2015-06-29 -->

PiGallery2 extensions are subdirectories within a configured extension folder. For Docker installations, this is typically config/extension/.

When the app starts or a configuration change occurs, it performs the following lifecycle:

1. Scans the extension folder for subdirectories.
2. If a package.js is present, it runs npm install for the dependencies listed there.
3. If a server.js is present, it calls the exported init(ext) function.

Extensions can implement an init function for setup and a cleanUp function to undo changes. The app calls init first, then cleanUp if it needs to re-initialize (e.g., during a config change).