From 016841b200b3991b4872b9efcf48123e410c8b03 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Mon, 2 Feb 2026 17:17:52 +0300 Subject: [PATCH] docs: reword documentation; provide more details on compartmentalization Signed-off-by: NotAShelf Change-Id: I21494f1b5a2256c12aa4496a9ea7de8f6a6a6964 --- README.md | 104 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 73 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index bedc45b..83315b9 100644 --- a/README.md +++ b/README.md @@ -7,57 +7,83 @@ collections, and audit logging. It supports both SQLite and PostgreSQL backends. ## Building -```sh +```bash # Build all compilable crates -cargo build -p pinakes-core -p pinakes-server -p pinakes-tui +$ 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 +$ cargo build -p pinakes-ui + +# Alternatively, while app deps are in PATH, you may simply build the entire +# workspace. +$ cargo build --workspace ``` ## Configuration -Copy the example config and edit it: +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 Pinales, you must +create your own configuration. You may copy the example config and edit it to +your needs: -```sh -cp pinakes.toml.example pinakes.toml +```bash +# Copy the sample config +$ cp pinakes.toml.example 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., `".*"`, +- `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 +- `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 -cargo run -p pinakes-server -- pinakes.toml -# or -cargo run -p pinakes-server -- --config pinakes.toml +# 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`). +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 -```sh -cargo run -p pinakes-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 +$ cargo run -p pinakes-tui -- --server http://localhost:3000 ``` -Keybindings: +#### Keybindings + +The TUI component of Pinakes is designed to be keyboard-centric, as it is +designed for the terminal. The keybindings are as follows: @@ -86,16 +112,24 @@ Keybindings: ### Desktop/Web UI -```sh -cargo run -p pinakes-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 ``` -Set `PINAKES_SERVER_URL` to point at the server if it is not on -`localhost:3000`. +> [!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`. ## API -All endpoints are under `/api/v1`. +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`. ### Media @@ -185,9 +219,17 @@ Metadata extraction uses lofty (audio, MP4), matroska (MKV), lopdf (PDF), epub ## Storage Backends -**SQLite** (default) -- Single-file database with WAL mode and FTS5 full-text -search. Bundled SQLite guarantees FTS5 availability. +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. -**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. +### **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.