add some mdbook documentation

11 files changed, 318 insertions, 0 deletions

diff --git a/doc/README.md b/doc/README.md
new file mode 100644
index 0000000..978fa48
--- /dev/null
+++ b/doc/README.md
@@ -0,0 +1,3 @@
+# Introduction
+
+Jellything is a server software to serve media like movies, videos and music through a website.
diff --git a/doc/SUMMARY.md b/doc/SUMMARY.md
new file mode 100644
index 0000000..9e8f4ab
--- /dev/null
+++ b/doc/SUMMARY.md
@@ -0,0 +1,12 @@
+# Summary
+
+[Introduction](README.md)
+
+- [Getting Started](getting-started/README.md)
+  - [Installation](getting-started/installation.md)
+  - [Setup](getting-started/setup.md)
+  - [Launch](getting-started/launch.md)
+- [Migrating the Database](migration.md)
+- [Paths](paths.md)
+- [Import Guide](import/README.md)
+  - [Metadata Providers](import/providers.md)
diff --git a/doc/book.toml b/doc/book.toml
new file mode 100644
index 0000000..5a8a779
--- /dev/null
+++ b/doc/book.toml
@@ -0,0 +1,8 @@
+[book]
+title = "Jellything Administrator Manual"
+src = "."
+
+[build]
+build-dir = "../target/book"
+
+[preprocessor.alerts]
diff --git a/doc/getting-started/README.md b/doc/getting-started/README.md
new file mode 100644
index 0000000..bad5562
--- /dev/null
+++ b/doc/getting-started/README.md
@@ -0,0 +1 @@
+# Getting Started
diff --git a/doc/getting-started/installation.md b/doc/getting-started/installation.md
new file mode 100644
index 0000000..7496b16
--- /dev/null
+++ b/doc/getting-started/installation.md
@@ -0,0 +1,24 @@
+# Installation
+
+## From the AUR
+
+This is the recommended option. It will also install a systemd service running
+in its own user.
+
+```sh
+git clone https://aur.archlinux.org/jellything-git.git
+cd jellything-git
+makepkg -si
+```
+
+## From source
+
+```sh
+git clone --recursive https://codeberg.org/metamuffin/jellything.git
+cd jellything
+cargo build --release
+# Global installation
+cp target/release/{jellything,jellytool} /usr/local/bin
+# User installation
+cp target/release/{jellything,jellytool} ~/.local/bin
+```
\ No newline at end of file
diff --git a/doc/getting-started/launch.md b/doc/getting-started/launch.md
new file mode 100644
index 0000000..d1d502f
--- /dev/null
+++ b/doc/getting-started/launch.md
@@ -0,0 +1,19 @@
+# Launch your Platform
+
+> [!TIP]
+> If you used the AUR package, this should be as simple as
+> `systemctl start jellything`.
+
+For other installations, run the `jellything` binary with the configuration
+file's path as its first argument or set it in `JELLYTHING_CONFIG`. Jellything
+will start and serve your library at
+[https://127.0.0.1:8080/](https://127.0.0.1:8080/)
+
+```sh
+jellything /etc/jellything.yaml
+JELLYTHING_CONFIG=/etc/jellything.yaml jellything
+```
+
+It is also advised to use jellything with a reverse proxy. Configure the network
+interface with the environment variables `BIND_ADDR` and `PORT`. Stderr logging
+can be configured with `LOG`.
diff --git a/doc/getting-started/setup.md b/doc/getting-started/setup.md
new file mode 100644
index 0000000..24182fc
--- /dev/null
+++ b/doc/getting-started/setup.md
@@ -0,0 +1,96 @@
+# Setup
+
+## 1. Writing configurations
+
+First write your configuration files whereever you want. The AUR package uses
+`/etc/jellything.yaml`.
+
+```yaml
+# This hostname must be identical to how other instances reach you.
+hostname: example.org
+brand: "Jellything"
+slogan: ""
+
+# All of these paths can be customized. See "Paths"
+media_path: "/srv/media"
+asset_path: "/var/lib/jellything/assets"
+database_path: "/var/lib/jellything/db"
+library_path: "/var/lib/jellything/library"
+temp_path: "/tmp/jellything"
+cache_path: "/var/cache/jellything"
+secrets_path: "/etc/jellysecrets.yaml" # points to the file below
+```
+
+```yaml
+# jellysecrets.yaml; filled with placeholders
+admin_password: "xxxxxx"
+
+# Both these keys should be initialized randomly.
+# Use `head -c 32 /dev/random | base64`
+cookie_key: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx="
+session_key: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx="
+
+# Credentials for remote instances. Keep this empty if you are just starting.
+federation:
+    "example.org": { username: "examplefed", password: "xxxxxxx" }
+
+api:
+    fanart_tv: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+    tmdb: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+    omdb: xxxxxxxx
+    # This is the Trakt Application `client_id`
+    trakt: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+    tvdb: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+## 2. Creating required directories
+
+Next create directories in place of `cache_path`, `temp_path`, `media_path`,
+`library_path` if jellything is not permitted to do so itself. Also obtain the
+default assets from git.
+
+```sh
+mkdir -p $cache_path $temp_path $media_path $library_path
+git clone https://codeberg.org/metamuffin/jellything-assets.git $asset_path
+```
+
+## 3. Preparing your first import
+
+In _library\_path_, create files like below. This file provides an entry point
+to your library. Its exact meaning is described in
+[The Import Guide](../import/README.md).
+
+```yaml
+# root.yaml
+id: library
+sources:
+  - !override
+    public:
+      kind: !collection
+      title: "My Library"
+      children:
+        - movies
+```
+
+```yaml
+# movies/directory.yaml
+id: movies
+sources:
+  - !override
+    public:
+      kind: !collection
+      title: "Movies"
+  - !auto_children
+```
+
+Next place your favorite movies in _media\_path_ and use the import helper to
+quickly generate import instructions for it. This requires at least Trakt and
+TMDB keys to work.
+
+```sh
+# This should be run from media_path since the path in -m is relative to that no matter PWD.
+# Jellytool will show an interactive wizard to select the correct metadata.
+jellytool add -m big-buck-bunny.mkv
+jellytool add -m agent-327-operation-barbershop.mkv
+jellytool add -m spring.mkv
+```
diff --git a/doc/import/README.md b/doc/import/README.md
new file mode 100644
index 0000000..d4e014c
--- /dev/null
+++ b/doc/import/README.md
@@ -0,0 +1,20 @@
+# Jellything's Import System
+
+In normal operation, jellything serves all metadata from only the database.
+
+Whenever you want to change this metadata, you initiate a Reimport from the
+admin panel. This will follow the import instructions in _library\_path_ and
+regenerate that part of the database from scratch.
+
+## The Import Procedure
+
+_library\_path_ is scanned recursively to locate all files that match `*.yaml`
+(YAML import options) or `*.jelly` (JSON import options). Each of these files
+contains a key `id` that specifies which node is primarily affected and an array
+`sources` which lists metadata providers. When all these files have been
+evaluated, each node's children are traversed recursively to generate their
+paths. The imported libraries structure is a directed acyclic graph (DAG) -
+nodes can have multiple parents.
+
+The Sources are applied in-order to that node with decreasing priority. This
+process merges all aquired metadata into single nodes.
diff --git a/doc/import/providers.md b/doc/import/providers.md
new file mode 100644
index 0000000..9b438c6
--- /dev/null
+++ b/doc/import/providers.md
@@ -0,0 +1,71 @@
+# Metadata Providers
+
+## `override`
+
+Allows for manual hardcoded metadata.
+
+Special to this option are the `poster` and `backdrop` properties in the
+`private` section. These are reference images local to _library\_path_ and
+directly set the counterparts in `public`.
+
+### Example
+
+```yaml
+id: library
+sources:
+  - !override
+    public:
+      kind: !collection
+      title: "My Library"
+      children:
+        - movies
+        - stuff
+    private:
+      poster: library.png
+```
+
+## `auto_children`
+
+Scans the directory of the file currently processed for `*.yaml` and `.jelly`,
+parses their ID and adds them as `children`.
+
+## `media`
+
+This references a media file on disk and links it to this node. Additionally it
+extracts matroska metadata aswell.
+
+> [!NOTE] 
+> If `path` is a directory, then these options are applied recursively
+> all files inside, automatically creating new nodes based on inferred IDs and
+> linking them up.
+
+### Example
+
+```yaml
+id: decay-2012
+sources:
+- !media
+  path: /movies/decay.webm
+  ignore_metadata: true
+  ignore_attachments: false
+  ignore_chapters: false
+```
+
+## `trakt`
+
+The recommended provider for any movie, show or season. It automatically queries
+other linked APIs.
+
+### Example
+
+```yaml
+id: decay-2012
+sources:
+- !trakt
+  kind: movie
+  id: 98052
+```
+
+## `tmdb`
+
+Just like `trakt` but uses only TMDB instead.
diff --git a/doc/migration.md b/doc/migration.md
new file mode 100644
index 0000000..089ebf7
--- /dev/null
+++ b/doc/migration.md
@@ -0,0 +1,38 @@
+# Migrating the Database
+
+With some updates the database serialization for changes. This requires a
+migration process. You need to follow this procedure either with every update.
+
+## 1. Export the database
+
+Use the `jellytool` of the previous version to export the database to JSON.
+
+```sh
+mv /path/to/db /path/to/db.old # Rename the DB to avoid conflict later
+jellytool.old migrate export /path/to/db.old export /tmp/jdb
+```
+
+## 2. Run migrations on the JSON dump
+
+> This is not implemented yet. It usually just works without anyway.
+
+## 3. Import the database
+
+Now import your library back to where it usually lives using the `jellytool` of
+the current version.
+
+```sh
+jellytool migrate export /path/to/db import /tmp/jdb
+```
+
+## 4. Delete old Databases
+
+Delete the old database and the JSON dump, they are not required anymore.
+
+> [!CAUTION]
+> Confirm that everything still works and no data ist lost
+
+```
+rm /path/to/db.old
+rm -r /tmp/jdb
+```
diff --git a/doc/paths.md b/doc/paths.md
new file mode 100644
index 0000000..4bbd2ef
--- /dev/null
+++ b/doc/paths.md
@@ -0,0 +1,26 @@
+# Paths
+
+- **media_path**: All your media (videos, movies, etc.) lives here. Jellything
+  will only require read-only access to this directory.
+- **asset_path**: Static assets for the page. This includes fallback images,
+  fonts and the front page. Used read-only.
+  - `error.avif`: Used when images cant be displayed because of an error. This
+    image is not required to be AVIF despite the name extension.
+  - `fallback-<kind>.avif`: Fallback image when there is no asset available.
+    AVIF also not required. `<kind>` is a _node kind_ or "Person".
+  - `front.htm`: Contents of the front page. The typical jellything page
+    scaffold is placed around it.
+  - `logo.svg`: Logo of the platform to replace the text in the top left of
+    every page.
+  - `fonts/material-icons.woff2` Material Icons Font. Get this from online.
+- **database_path**: The database stores all imported nodes, user accound and
+  such. Write access required.
+- **library_path**: This directory structure contains instructions for importing
+  your media.
+- **temp_path**: Where to place short-lived files. Write access required. Can be
+  in volatile memory (e.g. /tmp).
+- **cache_path**: In here jellything will place dozens of transcoded imagery,
+  saved api responses and media metadata. This folder will likely be the
+  biggest. Write access required.
+- **secrets_path**: Path to the `secrets` YAML file. Read access required.
+  Should ideally not be readable by anybody else than jellything.