NotAShelf
d61b5d32d1
Signed-off-by: NotAShelf <raf@notashelf.dev> Change-Id: I6caae0f7de73aa02150b48a3d7d8dcd06a6a6964
247 lines
9.2 KiB
Markdown
247 lines
9.2 KiB
Markdown
# Pinakes
|
|
|
|
[first known library cataloging system]: https://en.wikipedia.org/wiki/Pinakes
|
|
|
|
Pinakes, named after the [first known library cataloging system] designed to be
|
|
the _last library cataloging system you will ever need_. Pinakes indexes files
|
|
across configured directories, extracts metadata from audio, video, document and
|
|
text files, and provides full-text search with tagging, collections, roles,
|
|
audit logging and more. It supports both SQlite (for easy bootstrapping) and
|
|
PostgreSQL (production deployments) as available database backends.
|
|
|
|
## Building
|
|
|
|
This project uses [Just](https://just.systems/) as its command runner to help
|
|
run cargo with a consistent interface. You are recommended to get it with Nix,
|
|
using the default devshell which provides Just.
|
|
|
|
```bash
|
|
# Build everything (core crates + UI)
|
|
$ just build
|
|
|
|
# Build only core crates (cargo)
|
|
$ just build-core
|
|
|
|
# Build only the UI (uses dx - see note below)
|
|
$ just build-ui
|
|
```
|
|
|
|
> [!IMPORTANT]
|
|
> The Dioxus UI (`pinakes-ui`) must be built with `dx` (Dioxus CLI) to compile
|
|
> SCSS stylesheets. Using `cargo build -p pinakes-ui` will not work correctly as
|
|
> it skips the SCSS compilation step. This was previously "remedied" with an
|
|
> intermediate build wrapper, which turned out to be fragile. It is highly
|
|
> recommended that you prefer `just` to build.
|
|
|
|
Manual build commands if not using Just:
|
|
|
|
```bash
|
|
# Core crates (standard cargo)
|
|
$ cargo build -p pinakes-core -p pinakes-server -p pinakes-tui
|
|
|
|
# UI (requires Dioxus CLI for SCSS compilation)
|
|
$ dx build -p pinakes-ui
|
|
|
|
# System dependencies for the UI:
|
|
# On Debian/Ubuntu: apt install libgtk-3-dev libsoup-3.0-dev libwebkit2gtk-4.1-dev
|
|
# On Fedora: dnf install gtk3-devel libsoup3-devel webkit2gtk4.1-devel
|
|
# On Nix: Use the dev shell, everything is provided :)
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Pinakes runs with its own built-in configuration file out of the box. While
|
|
using the default configuration, you will not be able to edit the configuration
|
|
but it will provide the minimum required configuration values to get you going
|
|
with Pinakes. If you are more interested in fully configuring Pinakes, you must
|
|
create your own configuration. You may copy the example config and edit it to
|
|
your needs:
|
|
|
|
```bash
|
|
# Copy the sample config
|
|
$ cp pinakes.example.toml pinakes.toml
|
|
```
|
|
|
|
Key settings:
|
|
|
|
- `storage.backend` - `"sqlite"` or `"postgres"`
|
|
- `storage.sqlite.path` - Path to the SQLite database file
|
|
- `storage.postgres.*` - PostgreSQL connection parameters
|
|
- `directories.roots` - Directories to scan for media files
|
|
- `scanning.watch` - Enable filesystem watching for automatic imports
|
|
- `scanning.ignore_patterns` - Patterns to skip during scanning (e.g., `".*"`,
|
|
`"node_modules"`)
|
|
- `server.host` / `server.port` - Server bind address
|
|
|
|
## Running
|
|
|
|
All commands are available via Just. Run `just --list` to see all available
|
|
recipes.
|
|
|
|
### Server
|
|
|
|
To use Pinakes, you will need the server to be running. The GUI on its own will
|
|
work, but it will not be functional without the server.
|
|
|
|
```bash
|
|
# Using Just
|
|
$ just run-server
|
|
|
|
# Or manually:
|
|
$ cargo run -p pinakes-server -- pinakes.toml
|
|
```
|
|
|
|
The server starts on the configured host:port (default `127.0.0.1:3000`). In a
|
|
production scenario you are encouraged to reverse proxy the service, and prefer
|
|
SSL.
|
|
|
|
### TUI
|
|
|
|
The Pinakes TUI can be used to manage your collections from the comfort of your
|
|
terminal. While the server is running you may connect to it using the `--server`
|
|
flag.
|
|
|
|
```bash
|
|
# Using Just
|
|
$ just run-tui
|
|
|
|
# Or manually:
|
|
$ cargo run -p pinakes-tui
|
|
```
|
|
|
|
#### Keybindings
|
|
|
|
The TUI component of Pinakes is designed to be keyboard-centric, as it is
|
|
designed for the terminal. The keybindings are as follows:
|
|
|
|
<!-- markdownlint-disable MD013-->
|
|
|
|
| Key | Action |
|
|
| --------------------- | -------------------------------------------------------- |
|
|
| `q` / `Ctrl-C` | Quit |
|
|
| `j` / `k` | Navigate down / up |
|
|
| `Enter` | Select / confirm |
|
|
| `Esc` | Back |
|
|
| `/` | Search |
|
|
| `i` | Import file |
|
|
| `o` | Open file |
|
|
| `d` | Delete (media in library, tag/collection in their views) |
|
|
| `t` | Tags view |
|
|
| `c` | Collections view |
|
|
| `a` | Audit log view |
|
|
| `s` | Trigger scan |
|
|
| `r` | Refresh current view |
|
|
| `n` | Create new tag (in tags view) |
|
|
| `+` | Tag selected media (in detail view) |
|
|
| `-` | Untag selected media (in detail view) |
|
|
| `Tab` / `Shift-Tab` | Next / previous tab |
|
|
| `PageUp` / `PageDown` | Paginate |
|
|
|
|
<!-- markdownlint-enable MD013-->
|
|
|
|
### Desktop/Web UI
|
|
|
|
Pinakes features a fully fledged Desktop and Web UI powered by Dioxus. Those two
|
|
components are meant as a GUI frontend for the Pinakes server, and are
|
|
interchangeable in terms of usage.
|
|
|
|
> [!IMPORTANT]
|
|
> The UI must be run with `dx` (Dioxus CLI), not `cargo run`.
|
|
|
|
```bash
|
|
# Using Just
|
|
$ just run-ui
|
|
|
|
# Or manually with dx:
|
|
$ dx serve -p pinakes-ui
|
|
```
|
|
|
|
> [!TIP]
|
|
> By default Pinakes GUI will assume the server to be running on localhost and
|
|
> bound to port 3000. Set `PINAKES_SERVER_URL` to point at the server if it is
|
|
> not on `localhost:3000`.
|
|
|
|
### Extending Pinakes
|
|
|
|
While Pinakes _does_ aim to be as comprehensive as humanly possible, it is not
|
|
feasible to maintain all features in one gigantic repository without taking on
|
|
an immense technical debt. To avoid this kind of resource mismanagement while
|
|
still allowing for _all_ kinds of extension, Pinakes features two features at
|
|
your convenience:
|
|
|
|
- REST API Routes
|
|
- Plugin API
|
|
|
|
### REST API
|
|
|
|
[REST API documentation]: ./api.md
|
|
|
|
There exists a comprehensive UI for the server component that you may query
|
|
directly from the `/api/v1` endpoint. All other endpoints are under `/api/v1`.
|
|
|
|
The server API is, of course, a part of Pinakes core design but it is also how
|
|
first-party interfaces like `pinakes-ui` and `pinakes-tui` interact with the
|
|
server. You may write your own interfaces for a running Pinakes server with
|
|
minimal effort by simply sending requests to the API through your preferred
|
|
means. See [REST API documentation] on available routes and tips on how to
|
|
interact with the API.
|
|
|
|
### Plugin API
|
|
|
|
[Plugin API documentation]: ./plugins.md
|
|
|
|
The other method, which is by far the most powerful but also perhaps the least
|
|
polished as of writing is the **plugin system**. This is designed as a means of
|
|
implementing various user-facing features to Pinakes _server_ by writing your
|
|
own plugins that can modify certain elements. While this system is not as stable
|
|
as the server API, it is generally in good shape and example plugins are
|
|
provided. Please see the [Plugin API documentation] for more details, examples
|
|
and design.
|
|
|
|
## Storage Backends
|
|
|
|
Two storage backends are supported. For convenience, SQLite is the default
|
|
backend out of the box but for production deployments, with improved search and
|
|
scaling capabilities you may choose to prefer PostgreSQL. Both backends are
|
|
considered first-class citizens, and will be developed as such going further. If
|
|
your needs for Pinakes are modest, or if you are simply testing it out, SQLite
|
|
is the recommended database.
|
|
|
|
### **SQLite** (default)
|
|
|
|
Single-file database with WAL mode and FTS5 full-text search. Bundled SQLite
|
|
guarantees FTS5 availability.
|
|
|
|
### **PostgreSQL**
|
|
|
|
[pg_trgm]: https://www.postgresql.org/docs/current/pgtrgm.html
|
|
|
|
Native async with connection pooling (deadpool-postgres). Uses tsvector with
|
|
weighted columns for full-text search and [pg_trgm] for fuzzy matching. Requires
|
|
the `pg_trgm` extension.
|
|
|
|
## Contributing
|
|
|
|
[HACKING document]: ./HACKING.md
|
|
|
|
Pinakes, despite all the work going into it, is still in an early beta. Some of
|
|
the features still lack the polish they deserve and there _may_ be breaking
|
|
changes to the UI, databases, and the APIs. You may find a comprehensive
|
|
introduction to developing Pinakes in the [HACKING document].
|
|
|
|
It is generally advisable that you familiarize yourself with the codebase before
|
|
proposing or contributing changes. Pinakes consists of _many_ moving parts, and
|
|
it is better for the contributor experience to approach issues slowly and
|
|
discuss them beforehand.
|
|
|
|
## License
|
|
|
|
<!-- markdownlint-disable MD059 -->
|
|
|
|
[here]: https://interoperable-europe.ec.europa.eu/sites/default/files/custom-page/attachment/eupl_v1.2_en.pdf
|
|
|
|
This project is made available under European Union Public Licence (EUPL)
|
|
version 1.2. See [LICENSE](LICENSE) for more details on the exact conditions. An
|
|
online copy is provided [here].
|
|
|
|
<!-- markdownlint-enable MD059 -->
|