NotAShelf
c535650f45
Signed-off-by: NotAShelf <raf@notashelf.dev> Change-Id: I864882c5a22424cd6c8c320627fe9f006a6a6964
185 lines
7.1 KiB
Markdown
185 lines
7.1 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
|
|
|
|
```bash
|
|
# Build all compilable crates
|
|
$ cargo build -p pinakes-core -p pinakes-server -p pinakes-tui
|
|
|
|
# The Dioxus UI requires GTK3 and libsoup system libraries:
|
|
# 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 :)
|
|
$ cargo build -p pinakes-ui
|
|
|
|
# Alternatively, while app deps are in PATH, you may simply build the entire
|
|
# workspace.
|
|
$ cargo build --workspace
|
|
```
|
|
|
|
## 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
|
|
|
|
### 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.
|
|
|
|
```sh
|
|
# Start the server first
|
|
$ cargo run -p pinakes-server -- pinakes.toml
|
|
|
|
# or:
|
|
$ cargo run -p pinakes-server -- --config 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 defaults
|
|
$ cargo run -p pinakes-tui
|
|
|
|
# or with a custom server URL:
|
|
$ cargo run -p pinakes-tui -- --server http://localhost:3000
|
|
```
|
|
|
|
#### 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.
|
|
|
|
```bash
|
|
# Build the UI
|
|
$ cargo run -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 you may choose to prefer
|
|
PostgreSQL.
|
|
|
|
### **SQLite** (default)
|
|
|
|
Single-file database with WAL mode and FTS5 full-text search. Bundled SQLite
|
|
guarantees FTS5 availability.
|
|
|
|
### **PostgreSQL**
|
|
|
|
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.
|