self-hosted/pigallery2
1
0
Fork 0
mirror of https://github.com/bpatrik/pigallery2.git synced 2026-06-20 00:15:49 +02:00
Code Issues Releases Activity

Add FAQ and extension documentation.

Browse Source
This commit is contained in:
Patrik J. Braun
2026-01-23 14:25:42 +01:00
parent a64eac1827
commit cfb3d8713a
7 changed files with 159 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+12 -11
View File
@@ -11,27 +11,28 @@ PiGallery2 is a **fast** directory-first photo gallery website, optimized for ru
- **📁 Directory-first**: Shows your folder structure as it is.
- **Read-only**: Your photo folder is never modified.
[View full feature list and live demo](http://bpatrik.github.io/pigallery2/)
[Full documentation here](http://bpatrik.github.io/pigallery2/).
[Try our live demo!](https://pigallery2.onrender.com/) (First load may take up to 60s while the server boots up)
## 🏁 Getting Started
The official and recommended way to run PiGallery2 is using **Docker**.
### [Install with Docker (Recommended)](docs/setup/docker.md)
```bash
docker-compose up -d
```
### [Install with Docker (Recommended)](https://bpatrik.github.io/pigallery2/setup/docker)
### [Native Installation (Unsupported)](docs/setup/direct-install.md)
### [Native Installation (Unsupported)](https://bpatrik.github.io/pigallery2/setup/direct-install)
Native installation is possible for users familiar with Node.js but is not officially supported.
## 📖 Documentation
For more detailed information, please see our [Documentation Website](http://bpatrik.github.io/pigallery2/) or the `docs/` folder:
- [Configuration Guide](docs/user-guide/configuration.md)
- [User Rights](docs/user-guide/user-rights.md)
- [Contribution Guide](docs/development/contributing.md)
For more detailed information, please see our [Documentation Website](http://bpatrik.github.io/pigallery2) or the `docs/` folder:
- [FAQ (Frequently Asked Questions)](https://bpatrik.github.io/pigallery2/faq)
- [Configuration Guide](https://bpatrik.github.io/pigallery2/user-guide/configuration)
- [User Rights](https://bpatrik.github.io/pigallery2/user-guide/user-rights)
- [Contribution Guide](https://bpatrik.github.io/pigallery2/development/contributing)
## 🤝 Contributing
Contributions are welcome! Please read our [Contribution Guide](docs/development/contributing.md) to get started.
Contributions are welcome! Please read our [Contribution Guide](https://bpatrik.github.io/pigallery2/development/contributing) to get started.
## ⭐ Star History
[![Star History Chart](https://api.star-history.com/svg?repos=bpatrik/pigallery2&type=date&legend=top-left)](https://www.star-history.com/#bpatrik/pigallery2&type=date&legend=top-left)
docs/development/assets/events.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 56 KiB

docs/development/extensions.md
+113
View File
@@ -0,0 +1,113 @@
# PiGallery2 Extension
See the feature issue for more information: [#743](https://github.com/bpatrik/pigallery2/issues/743).
See the sample extension at https://github.com/bpatrik/pigallery2-sample-extension.
# Extension Usage
Extension folder can be set through config. For the docker-ised version,
they live under the `config/extension` folder in their own subdirectory.
# Extension development
## Minimal setup
You need at least a `server.js` in your extension folder that exports a `init(ext) {}` function.
## Recommended setup
```
<path to the extension fodler>/myextension/package.js <- this is optional. You can add extra npm packages here
<path to the extension fodler>/myextension/server.js <- this is needed
```
Where `<path to the extension fodler>` is what you set in the config and `myextension` is the name of your extension.
Note: you do not need to add your `node_modules` folder. The app will call `npm install` when initializing your extension.
## Extension environment
The app runs the extension the following way:
- It reads all extensions in `<path to the extension fodler>/**` folder
- Checks if `package.js` is present. If yes, installs the packages
- Checks if `server.js` is present. If yes, calls the `init` function.
### Init and cleanup lifecycle
There is also a `cleanUp` function that you can implement in your extension.
The app can call your `init` and `cleanUp` functions any time.
Always calls the `init` first then `cleanUp` later.
Main use-case: `init` is called on app startup. `cleanUp` and `init` called later when there is a config change.
## Extension interface
The app calls the `init` and `cleanUp` function with a `IExtensionObject` object.
See https://github.com/bpatrik/pigallery2/blob/master/src/backend/model/extension/IExtension.ts for details.
`IExtensionObject` exposes lifecycle events, configs, RestAPis with some limitation.
Changes made these public apis you do not need to clean up in the `cleanUp` function.
App also exposes private `_app` object to provide access to low level API. Any changes made here need cleanup.
## server.js
See sample server.js at https://github.com/bpatrik/pigallery2-sample-extension.
It is recommended to do the development in `ts`, so creating a `server.ts`.
Note: You need to manually transpile your `server.ts` file to `server.js` as the app does not do that for you.
This doc assumes you do the development in `ts`.
### server.ts
You can import package from both the main app package.json and from your extension package.json.
To import packages from the main app, you import as usual.
For packages from the extension, you always need to write the relative path. i.e.: prefix with `./node_modules`
```ts
// Including dev-kit interfaces. It is not necessary, only helps development with types.
// You need to prefix them with ./node_modules
import { IExtensionObject } from "./node_modules/pigallery2-extension-kit";
// Including prod extension packages. You need to prefix them with ./node_modules
// lodash does not have types
// eslint-disable-next-line @typescript-eslint/ban-ts-comment
// @ts-ignore
import * as _ from "./node_modules/lodash";
// Importing packages that are available in the main app (listed in the packages.json in pigallery2)
import { Column, Entity, Index, PrimaryGeneratedColumn } from "typeorm";
```
#### pigallery2 extension dev-kit
It is recommended to use the `pigallery2-extension-kit` node package.
`npm install pigallery2-extension-kit --save` to your extension.
`pigallery2-extension-kit` contains the type definitions and enums for the app.
This node package basically includes the all definitions of the app and exports the `IExtensionObject` that the `init` function receives.
You can then `import {IExtensionObject} from './node_modules/pigallery2-extension-kit';`
See https://github.com/bpatrik/pigallery2/blob/master/src/backend/model/extension/IExtension.ts to understand what contains `IExtensionObject`.
NOTE: this is not needed to create an extension it only helps your IDE and your development. These type definitions are removed when you compile `ts` to `js`.
#### `init` function
You need to implement the `init` function for a working extension:
```ts
export const init = async (extension: IExtensionObject<void>): Promise<void> => {};
```
#### pigallery2 lifecycle `events`
The app exposes multiple interfaces for the extensions to interact with the main app. `events` are one of the main interfaces.
Here is their flow:
![events_lifecycle](assets/events.png)
### Publishing your extension
Add a new row to the https://github.com/bpatrik/pigallery2/blob/master/extension/REPOSITORY.md to publish your extension. Pigellery2 reads the online version of the file to chek for available extensions (no need to rebuidl the app).
docs/faq.md
+19
View File
@@ -0,0 +1,19 @@
# Frequently Asked Questions (FAQ)
??? info "Why are there no albums, only logical albums (saved search)?"
PiGallery2 follows a philosophy where the **disk is the source of truth and the database is only a cache**. The application is designed to show your photos as they are organized on your storage.
Because the database is treated as a cache, it can be deleted and rebuilt at any time without losing your photo organization. "Logical albums" (saved search queries) are used instead of traditional database-only albums to maintain this directory-first approach and ensure that your gallery remains portable and easy to rebuild.
If you still need traditional album-like behavior, you can use one of these workarounds:
1. **Custom Keywords**: Add a unique keyword to your photos in their metadata (e.g., using Lightroom or DigiKam). You can then create a **Logical Album** in PiGallery2 by searching for that keyword.
2. **Extensions**: You can develop an extension that automatically adds the keywords and creates albums for you. (see [discussion 1110](https://github.com/bpatrik/pigallery2/discussions/1110)
??? info "Why are there breaking changes in the database or config?"
To maintain high **development velocity**, we do not provide database upgrade scripts. PiGallery2 is a hobby project, and implementing/debugging complex migration scripts would significantly slow down the addition of new features.
As the database is only a cache, it is expected that users might need to delete the database and/or restart the configuration after a new release. This allows the project to move fast and evolve without being held back by legacy structures.
??? info "Why are there no regular releases?"
PiGallery2 is a **hobby project** developed in free time. The developer does not get paid for this work and maintains it alongside a full-time job and other life commitments. Releases happen when new features are ready and time permits, rather than on a fixed schedule.
docs/index.md
+4
View File
@@ -4,6 +4,7 @@ Welcome to the official documentation for PiGallery2!
PiGallery2 is a **fast** directory-first photo gallery website, optimized for running on low-resource servers (especially on Raspberry Pi).
[Try our live demo!](https://pigallery2.onrender.com/) (First load may take up to 60s while the server boots up)
![PiGallery2 Demo](assets/demo.gif)
## 🧭 Navigation
@@ -11,6 +12,9 @@ PiGallery2 is a **fast** directory-first photo gallery website, optimized for ru
### ✨ [Features](features.md)
Check out the full list of features and see what PiGallery2 can do for you.
### ❓ [FAQ](faq.md)
Answers to frequently asked questions about the project's philosophy and releases.
### 🏁 [Getting Started](setup/docker.md)
Learn how to install PiGallery2 using Docker (recommended) or via a native installation.
extension/README.md
+3 -106
View File
@@ -1,108 +1,5 @@
# pigallery2 Extension
# PiGallery2 Extension
See feature issue for more information: [#743](https://github.com/bpatrik/pigallery2/issues/743).
This folder contains the core of the extension system.
See sample extension at https://github.com/bpatrik/pigallery2-sample-extension.
# Extension Usage
Extension folder can be set through config. For the docker-ised version,
they live under the `config/extension` folder in their own subdirectory.
# Extension development
## Minimal setup
You need at least a `server.js` in your extension folder that exports a `init(ext) {}` function.
## Recommended setup
```
<path to the extension fodler>/myextension/package.js <- this is optional. You can add extra npm packages here
<path to the extension fodler>/myextension/server.js <- this is needed
```
Where `<path to the extension fodler>` is what you set in the config and `myextension` is the name of your extension.
Note: you do not need to add your `node_modules` folder. The app will call `npm install` when initializing your extension.
## Extension environment
The app runs the extension the following way:
- It reads all extensions in `<path to the extension fodler>/**` folder
- Checks if `package.js` is present. If yes installs the packages
- Checks if `server.js` is present. If yes, calls the `init` function.
### Init and cleanup lifecycle
There is also a `cleanUp` function that you can implement in your extension.
The app can call your `init` and `cleanUp` functions any time.
Always calls the `init` first then `cleanUp` later.
Main use-case: `init` is called on app startup. `cleanUp` and `init` called later when there is a new config change.
## Extension interface
The app calls the `init` and `cleanUp` function with a `IExtensionObject` object.
See https://github.com/bpatrik/pigallery2/blob/master/src/backend/model/extension/IExtension.ts for details.
`IExtensionObject` exposes lifecycle events, configs, RestAPis with some limitation.
Changes made during the these public apis you do not need to clean up in the `cleanUp` function.
App also exposes private `_app` object to provide access to low level API. Any changes made here needs clean up.
## server.js
See sample server.js at https://github.com/bpatrik/pigallery2-sample-extension.
It is recommended to do the development in `ts`, so creating a `server.ts`.
Note: You need to manually transpile your `server.ts` file to `server.js` as the app does not do that for you.
This doc assumes you do the development in `ts`.
### server.ts
You can import package from both the main app package.json and from your extension package.json.
To import packages from the main app, you import as usual.
For packages from the extension, you always need to write relative path. i.e.: prefix with `./node_modules`
```ts
// Including dev-kit interfaces. It is not necessary, only helps development with types.
// You need to prefix them with ./node_modules
import { IExtensionObject } from "./node_modules/pigallery2-extension-kit";
// Including prod extension packages. You need to prefix them with ./node_modules
// lodash does not have types
// eslint-disable-next-line @typescript-eslint/ban-ts-comment
// @ts-ignore
import * as _ from "./node_modules/lodash";
// Importing packages that are available in the main app (listed in the packages.json in pigallery2)
import { Column, Entity, Index, PrimaryGeneratedColumn } from "typeorm";
```
#### pigallery2 extension dev-kit
It is recommended to use the `pigallery2-extension-kit` node package.
`npm install pigallery2-extension-kit --save` to your extension.
`pigallery2-extension-kit` contains the type definitions and enums for the app.
This node package is basically includes the all definitions of the app and exports the `IExtensionObject` that the `init` function receives.
You can then `import {IExtensionObject} from './node_modules/pigallery2-extension-kit';`
See https://github.com/bpatrik/pigallery2/blob/master/src/backend/model/extension/IExtension.ts to understand what contains `IExtensionObject`.
NOTE: this is not needed to create an extension it only helps your IDE and your development. These type definitions are removed when you compile `ts` to `js`.
#### `init` function
You need to implement the `init` function for a working extension:
```ts
export const init = async (extension: IExtensionObject<void>): Promise<void> => {};
```
#### pigallery2 lifecycle `events`
Tha app exposes multiple interfaces for the extensions to interact with the main app. `events` are one of the main interfaces.
Here are their flow:
![events_lifecycle](events.png)
For extension development and usage, please see the [documentation](https://bpatrik.github.io/pigallery2/development/extensions/).
mkdocs.yml
+8
View File
@@ -1,10 +1,14 @@
site_name: PiGallery2 Documentation
site_url: https://bpatrik.github.io/pigallery2/
theme:
name: material
palette:
primary: indigo
accent: indigo
plugins:
- search
- glightbox
@@ -17,6 +21,8 @@ markdown_extensions:
pygments_lang_class: true
- pymdownx.inlinehilite
- pymdownx.snippets
- admonition # Required for the "info" blocks
- pymdownx.details # Required for the "???" collapsible behavior
- pymdownx.superfences:
custom_fences:
- name: mermaid
@@ -24,6 +30,7 @@ markdown_extensions:
format: !!python/name:pymdownx.superfences.fence_code_format
nav:
- Home: index.md
- FAQ: faq.md
- Features: features.md
- Getting Started:
- Docker (Recommended): setup/docker.md
@@ -37,6 +44,7 @@ nav:
- Development:
- Contributing: development/contributing.md
- Docker Development: development/docker-contributing.md
- Extensions: development/extensions.md
- Blog:
- How do I use PiGallery2 (2021): blog/How do I use PiGallery2 2021.md
- The future of PiGallery2 (2023): blog/The future of pigallery2 v2.0.0 and beyond 2023.md