Skip to content

PiGallery2 Contribution guide (draft)

Intro

PiGallery2 has grown beyond what one person can maintain alone. Community contributions as extension or pull requests (PRs) are highly welcome!

Bug fixes first

PiGallery2 is a hobby project with a single maintainer, done in free time next to a day job and a family: about 1-2 releases and 4-5 medium features a year. The maintainer mostly merges bug fixes; feature PRs have a low chance of being reviewed. To keep the app simple, the core stays small and features move to extensions.

To keep development organized, please follow our feature workflow and rule of thumb before writing code.

Feature Contribution Workflow

  1. Without code: Check whether an existing setting or a theme (custom CSS, Gallery.Themes setting) already does it.
  2. As an Extension: If possible, implement your new feature entirely as an isolated extension. Extensions can also change the settings and the theme.
  3. Improve Extension Support: If the current architecture doesn't support your extension, send a PR to improve extension support first, then add your feature as an extension.
  4. Consult the Maintainer: If adding extension support is not technically possible, open an issue to consult with the maintainer first before making changes to the core code.

Before Submitting a PR

Always open an issue/ticket first to discuss your planned changes. This ensures your hard work aligns with the project roadmap and can be safely merged!

How to develop

  1. Download the source files
  2. install dependencies npm install
  3. Build client npm run run-dev
  4. This will build the client with english localization and will keep building if you change the source files.
  5. Note: This process does not exit, so you need another terminal to run the next step.
  6. Build the backend npm run build-backend
  7. This runs tsc that transpiles .ts files to .js so node can run them.
    • To rebuild on change run tsc -w
  8. Note: you can skip this test if you use and IDE that supports typescript (e.g.: webstorm, vscode)
  9. Run the server npm start

Releasing

The pigallery2-extension-kit npm package is published by CI (.github/workflows/ci.yml) with the app's version, once per version: bump the version in package.json; prereleases (e.g. 4.0.0-edge) publish from master with the npm dist-tag edge, stable versions from their release tag (the tag must equal the version) with latest. Build it locally with npm run build-extension-interface.

Developing with AI agents

The repository contains an AGENTS.md file with project context, commands and rules for AI coding agents. Most agents (Claude Code, Junie, Codex, Cursor, Copilot, etc.) pick it up automatically; for others, point them to it. It is also a short summary of the project's priorities, so it is worth a read for human contributors too.

Developer docs

Project structure

Overview:

|-- benchmark --A benchmark tool to test the speed of the app (not needed for development)
|-- demo -- contains some sample photo for https://pigallery2.onrender.com/  (not needed for development)
|-- docker -- contains all docker and docker realted configurations (this is the recommended way for app deplyoment)
|-- docs -- webpage for http://bpatrik.github.io/pigallery2/

|-- src -- contains the rource files <-------- This is what you need
|-- test -- contains the unit and integration tets <----- be nice and write tests to your feature

Source structure:

|-- src -- contains the rource files <-------- This is what you need
  |-- backend -- nodejs backend code
  |-- common -- shared files (mostly DTOs) between the frontend and the backend
  |-- frontend -- angular based frontend

Backend structure:

|-- src -- contains the rource files <-------- This is what you need
  |-- backend -- nodejs backend code
    |-- middlewares -- contains the middlewares. These make minimal input validation and transforamtion
    |-- model -- contains the business logic
      |-- database -- SQL (TypeORM) based business logic, these return with the gallery related data
        |-- enitites -- TypeORM entities
      |-- diagnostics -- contains the checks for the startup diagnostics (checks if all the settings are valid, all packeges are avaiale, image folder exists, etc.)
      |-- extension -- extension runtime and the public extension interface
      |-- fileaccess -- disk and file related code
        |-- DiskManager.ts -- scans a direcory
        |-- MetadataLoader.ts -- parses a photo / video for metadata
        |-- *Worker.ts -- queues and helper classes to convert video / photo
        |-- fileprocessing -- photo and video converting code
      |-- jobs -- code about job scheduling (crontab like feature)
      |-- messenger -- notification messengers (e.g.: email)
    |-- routes -- contains the declarations of the HTTP Api endpoints
    |-- index.ts -- here starts the Server up (callst server.ts)
    |-- server.ts -- this is HTTP server startup code
    |-- ProjectPath.ts -- singleton, contains the project related paths

Case-study: Listing a directory

Scenario: Web UI wants to show the /demoDir directory, using SQL database with low reindexing severity.

Client side:

  1. Navigating to http://<domain>/demoDir
  2. URL changed: [gallery.component.ts]: onRoute triggered
  3. Calling: [gallery.component.ts]: galleryService.loadDirectory('/demoDir')
  4. Loading data from local_storage: [gallery.service.ts]: galleryCacheService.getDirectory('/demoDir')
  5. Make a call to backend if the content changed [gallery.service.ts]: networkService.getJson<ContentWrapperWithError>('/gallery/content/' + '/testDir', params)
    • params contains last modification and last scanned date that is know from the local_storage cache

Server side:

  1. Requests hits the server in [GalleryRouter.ts]: protected static addDirectoryList(app: Express): https://github.com/bpatrik/pigallery2/blob/b79d62840c7496b5068d6af73f10d95b9ac48fdd/src/backend/routes/GalleryRouter.ts#L32-L46

  2. Authenticating user: [AuthenticationMWs.ts]: AuthenticationMWs.authenticate

    • On fail return with error
  3. Normalizing directory path parameter (in this case /testDir): [AuthenticationMWs.ts]: AuthenticationMWs.normalizePathParam('directory')
    • Makes sure that path does not go out of the allowed paths (gallery itself)
  4. Checking if the path exists and the User has rights to access it: [AuthenticationMWs.ts]:AuthenticationMWs.authorisePath('directory', true)
    • returns 403 if not accessible
  5. Injecting gallery version to the HTTP header: [VersionMWs.ts]:VersionMWs.injectGalleryVersion
    • gallery version is a hash that represents the current gallery status (latest modified date, number of photos/videos, etc)
  6. Getting the content of /testDir [GalleryMWs]: GalleryMWs.listDirectory
    1. If the last modificatoin and scan date of /testDir equals with what the client have sent, returning empty result to the client (skipping the rest)
    2. If last modification date is different from what the client knew, reindexing /testDir: IndexingManager.indexDirectory(relativeDirectoryName)
      • Scans a directory, asynchronously saves it to DB, while directly retourns with raw results from DiskManagerWorker.ts
    3. If Last scan heppened a while ago, reindex it asynchronously and return data from DB
  7. Attaching Thumbnails data to the photos/videos: [ThumbnailGeneratorMWs]: ThumbnailGeneratorMWs.addThumbnailInformation
    • Checks if a photo already has a generated thumbnail image
  8. Removes empty properties and circular dependencies: [GalleryMWs.ts]: GalleryMWs.cleanUpGalleryResults
  9. Rending http body and ending HTTP call: [RenderingMWs.ts]: RenderingMWs.renderResult

Client side:

  1. Setting content BehaviorSubject (rxjs) with the ContentWrapperWithError from the server.
  2. Rendering gallery: UI is data binded to the galleryService.content [gallery.component.html]

Running the tests locally

You can run tests in various ways. If you use VS Code, the built-in test explorer is a good way to visualize and run the tests. You can also run tests from the command line.

Note: mocha runs the transpiled .js files, so run npm run build-backend (or tsc -w) first.

  • Run all tests:

npx mocha - Run all tests in parallel and report with very verbose output (to debug tests that don't run):

npx mocha --reporter spec --parallel - Run a specific test (here the SettingsRouter in the backend):

npx mocha ./test/backend/integration/routers/admin/SettingsRouter.js

MySQL / MariaDB tests

The MySQL / MariaDB tests needs a separate database to be running during the test. If you have docker, you can start one with the required test-settings, using the command below:

docker run --name pigallery_test -e MYSQL_ROOT_PASSWORD=password -e MYSQL_DATABASE=pigallery_test -e MYSQL_USER=user -e MYSQL_PASSWORD=password -p3306:3306 -d mariadb:10.3 --log-bin --binlog-format=MIXED

Start this betfore running the tests in text explorer or the command line, if you want to include the MySQL tests.

To skip the MySQL tests (SQLite only, good enough for quick development), set TEST_MYSQL=false: TEST_MYSQL=false npx mocha (bash) or $env:TEST_MYSQL="false"; npx mocha (PowerShell). Before submitting a PR, run the full suite including MySQL.

Once you're finished with the testing, you can shut down the container again:

docker stop pigallery_test

or you can shut it down AND remove it:

docker stop pigallery_test && docker rm pigallery_test