diff --git a/docs-developers/architecture/release-pipeline.md b/docs-developers/architecture/release-pipeline.md index 2b83cac..f00b98c 100644 --- a/docs-developers/architecture/release-pipeline.md +++ b/docs-developers/architecture/release-pipeline.md @@ -147,6 +147,22 @@ transcoding/probing (both are optional by design) and retries on the next start. The `.deb`/`.rpm` packages sidestep all of this by declaring a dependency on the distro's `ffmpeg`. +### Smoke test, and the LinuxServer.io image downstream + +`release.yml`'s last step smoke-tests the archives while the release is still a +draft: the exact linux archive names, the binary at each archive's root, each +binary's `embedplayer` tag, `CGO_ENABLED=0` and architecture (`go version -m`), and +an amd64 boot with `--data` only (the headless first run and the self-signed TLS +default) that must serve `/healthz` and `/web/`. + +That is a contract, because +[linuxserver/docker-audiosilo](https://github.com/linuxserver/docker-audiosilo) +(`lscr.io/linuxserver/audiosilo`, the image Unraid's Community Applications lists) +installs `audiosilo__linux_{amd64,arm64}.tar.gz` from the published release +onto Alpine. Their CI polls `releases/latest` hourly, so publishing the draft is +what triggers a new `-ls` image. The full list is in +`audiosilo-server/RELEASING.md` section 2c. + ## 4. Manager desktop builds - `audiosilo-manager/.github/workflows/desktop.yml` The Wails UI can't cross-compile, so `desktop.yml` runs a per-OS matrix on `v*` @@ -173,6 +189,10 @@ Gatekeeper/SmartScreen warnings. re-run them after. On a plain tag push all workflows fire together; the web image resolved is whatever `:latest` (or the dispatched `web_version`) points at, which is why the runbook publishes the web image first. +- **Publish the native draft last.** The draft is uploaded before `release.yml`'s + smoke test runs, and publishing it is what the LinuxServer.io image follows: + publish only once the run is green, and tick *Set as a pre-release* for a `-rc` + tag. - **Docker vs. native:** same server code, same pinned player; the differences are ffmpeg (bundled in the image, resolved/fetched at runtime for binaries) and how the player is attached (`/app/web` + `AUDIOSILO_WEB_DIR` vs. `-tags embedplayer`). diff --git a/docs-developers/contributing/documentation.md b/docs-developers/contributing/documentation.md index 98c204d..ef87e40 100644 --- a/docs-developers/contributing/documentation.md +++ b/docs-developers/contributing/documentation.md @@ -79,7 +79,7 @@ mappings: | `pkg/query`, `pkg/query/querytest`, `pkg/release` in audiosilo-meta, or the artifact schema | [meta/overview.md](../meta/overview.md#public-go-packages) + [meta/data-model.md](../meta/data-model.md#the-compiled-artifact-and-schema-versioning) + the [cross-repo contract](../architecture/cross-repo-contract.md#14-community-metadata-a-three-repo-seam) (mirror-mode servers read the artifact directly) | | Meta schemas, `metaserve` API, or intake tooling | [meta developer pages](../meta/overview.md) (data model, API, contributing) - and the [cross-repo contract](../architecture/cross-repo-contract.md) when the server's `/meta` envelope is affected | | meta.audiosilo.app site UI | `/users/community/meta-site` + the `meta/` screenshots (+ [meta/overview.md](../meta/overview.md) when it is a site-architecture change) | -| Build / release / distribution | [release-pipeline.md](../architecture/release-pipeline.md) + [releasing.md](./releasing.md) | +| Build / release / distribution | [release-pipeline.md](../architecture/release-pipeline.md) + [releasing.md](./releasing.md) (+ `/users/getting-started/install-unraid` when the native archives or the LinuxServer.io image's template, paths or defaults change) | | A capability flag | [server/api/index.md](../server/api/index.md) + the feature's user page | :::tip diff --git a/docs-developers/contributing/releasing.md b/docs-developers/contributing/releasing.md index 8268b6b..02dcd11 100644 --- a/docs-developers/contributing/releasing.md +++ b/docs-developers/contributing/releasing.md @@ -18,6 +18,7 @@ step-by-step runbook. The maintainer notes it follows are | `ghcr.io/kodestar/audiosilo-web` | `audiosilo-frontend/.github/workflows/web.yml` | push to `main` (`:latest`); `v*` tags (semver) | GHCR - a tiny image holding only the static web export (`baseUrl=/web`) | | `ghcr.io/kodestar/audiosilo-server` | `audiosilo-server/.github/workflows/image.yml` | `v*` tags; manual dispatch | GHCR - the deployable image, web player baked in at `/app/web` | | Native server binaries | `audiosilo-server/.github/workflows/release.yml` (GoReleaser) | `v*` tags; manual dispatch | **Draft** GitHub Release on `KodeStar/audiosilo-server` | +| `lscr.io/linuxserver/audiosilo` | LinuxServer.io's CI ([linuxserver/docker-audiosilo](https://github.com/linuxserver/docker-audiosilo)) | publishing a server release (polled hourly) | Docker Hub / GHCR / lscr.io, and Unraid Community Applications | | iOS / Android apps | EAS Build (manual, outside CI) | on demand | App Store Connect / Google Play Console | | Manager desktop app | `audiosilo-manager/.github/workflows/desktop.yml` | `v*` tags; manual dispatch | Workflow artifacts (installers via GitHub Releases are **planned**) | @@ -83,7 +84,11 @@ amd64/arm64 all cross-compile from one Linux runner. - Outputs: `.tar.gz` (Linux/macOS), `.zip` (Windows), `.deb`/`.rpm` (which depend on the distro's ffmpeg and install a systemd unit), and `checksums.txt`. - The GitHub Release is created as a **draft** - a human reviews the notes and - artifacts, then publishes. The notes end with GoReleaser's `release.footer`, + artifacts, then publishes. The draft appears before the workflow finishes: its + last step then smoke-tests the uploaded archives, so **publish only once the run + is green**. Publishing is also what triggers the LinuxServer.io image (see + [the release pipeline](../architecture/release-pipeline.md#smoke-test-and-the-linuxserverio-image-downstream)). + The notes end with GoReleaser's `release.footer`, which also carries the one sponsor line ("AudioSilo is free; sponsors keep it going", linking GitHub Sponsors, the same message as the admin console's update notice). Keep it when you rewrite the notes by hand, and add nothing more (no @@ -104,7 +109,10 @@ real console.) ## Versions and tags - Releases are **`v`-prefixed semver tags** (`v*`) on each repo; there is no - cross-repo version lockstep. The server↔web pairing is by **image pinning**, + cross-repo version lockstep. GoReleaser does not mark a pre-release tag (for + example `v2.1.0-rc1`) as a pre-release itself: tick **Set as a pre-release** + when publishing one, or `releases/latest` moves to it and the LinuxServer.io + image ships it to every Unraid install. The server↔web pairing is by **image pinning**, not version numbers, and native apps negotiate against any server version via the `GET /server` capability flags. - The server version string comes from the release tag via ldflags diff --git a/docs-users/getting-started/install-unraid.md b/docs-users/getting-started/install-unraid.md new file mode 100644 index 0000000..a52ecf9 --- /dev/null +++ b/docs-users/getting-started/install-unraid.md @@ -0,0 +1,78 @@ +--- +title: Install on Unraid +description: "Install AudioSilo on Unraid from Community Applications using the LinuxServer.io image: paths, first-run credentials, HTTPS and reverse proxies, and updates." +--- + +## Install on Unraid + +On Unraid, install AudioSilo from **Community Applications** (the Apps tab). The app there is the [LinuxServer.io](https://www.linuxserver.io) image, **`lscr.io/linuxserver/audiosilo`**: the same server, web player and ffmpeg as the [Docker quick start](./quickstart-docker.md), packaged the LinuxServer.io way and rebuilt automatically after every AudioSilo release (usually within an hour or two). + +### 1. Install the app + +1. Open the **Apps** tab and search for **AudioSilo**. +2. Pick the one from **linuxserver's Repository** and click **Install**. +3. Fill in the template: + - **Audiobooks** (`/audiobooks`) - your audiobooks share, for example `/mnt/user/audiobooks`. It is mounted read-only: the server never writes to your books. + - **WebUI** (the port) - `8080` unless it's taken on your server. +4. Click **Show more settings** for the rest of the template: + - **Appdata** (`/config`) - where the server keeps its database, `config.yaml` and TLS certificates. Unraid usually pre-fills your default appdata location; prefer a cache or pool path such as `/mnt/cache/appdata/audiosilo` so the database isn't on the slower user-share layer. + - **PUID / PGID** - leave the Unraid defaults, `99` and `100` (`nobody:users`). +5. Click **Apply**. + +### 2. Grab your credentials + +On the very first start, the server creates an admin account and prints the credentials **once** in the container log. In the **Docker** tab, click the AudioSilo icon and choose **Logs**: + +```text +======================================================== + AudioSilo first-run setup - store these now, shown once +======================================================== + Admin username : admin + Admin password : + Auth code : + Config file : /config/config.yaml +``` + +Save the password and the auth code now - they are never shown again. See [First run](./first-run.md) for what each is for and what to do if you miss them. + +### 3. Open it and add your library + +Click the AudioSilo icon and choose **WebUI**. By default the server speaks HTTPS with a self-signed certificate, so your browser warns about the certificate the first time; accept it to continue. + +- **`/`** - the connect page, where a listener enters an auth code to pair a device. +- **`/admin`** - the admin console. Log in as `admin` with the printed password. +- **`/web`** - the web player. + +In the admin console, click **Add your first library** and point it at **`/audiobooks`** (the path inside the container, not the `/mnt/user/...` share). See [Libraries](../admin/libraries.md) for the details, then [connect a phone or browser](../listening/connecting.md). + +### HTTPS and reverse proxies + +The default self-signed certificate is fine on your home network. To reach AudioSilo from outside, the usual Unraid route is a reverse proxy such as **SWAG** or Nginx Proxy Manager terminating HTTPS in front of it. All three settings it needs are in the admin console under **Server > Settings**: + +- Point the proxy at `https://:8080` as it is, or set **HTTPS mode** to **Off**, restart the container, and point the proxy at `http://:8080`. With HTTPS off, the Docker tab's **WebUI** entry still opens `https://`: edit the container, switch to **Advanced View**, and change its **WebUI** field to `http://[IP]:[PORT:8080]`. +- Set **Public address** to the address your users reach it at (for example `https://books.example.com`) so invite links and QR codes point there. +- Add the proxy's address to **Trusted proxies** so rate limiting sees the real visitor's address. + +[Remote access](./remote-access.md) covers all of this, plus Let's Encrypt without a proxy. + +:::warning +Only set HTTPS mode to Off behind a proxy that terminates HTTPS. Plain HTTP exposed directly to the internet sends passwords and audio unencrypted. +::: + +Most settings can also be set with an `AUDIOSILO_*` variable, such as `AUDIOSILO_PUBLIC_URL` or `AUDIOSILO_TLS_MODE` (add it with **Add another Path, Port, Variable, Label or Device** on the template's edit page). A variable wins over the console, which then shows that setting as locked. + +### Updating + +Unraid's Docker tab shows **update ready** when a new image is out; apply it there (or let the CA Auto Update plugin do it). The image follows AudioSilo's releases automatically, and also picks up Alpine and ffmpeg security updates weekly. Your appdata and books are untouched by updates. + +### Moving from the AudioSilo image + +Already running `ghcr.io/kodestar/audiosilo-server` on Unraid? The data is the same; only the paths inside the container differ: `/config` here instead of `/data`, and `/audiobooks` instead of `/library` for your books. + +1. Note any `AUDIOSILO_*` variables the old container sets, such as `AUDIOSILO_PUBLIC_URL` or `AUDIOSILO_TLS_MODE`. They live in the container's settings, not in `config.yaml`, so they don't move on their own. (Skip `AUDIOSILO_WEB_DIR`: this image has the web player built in.) +2. Stop and remove the old container. Its data stays in its folder. +3. In that folder, edit `config.yaml` and change any path that starts with `/data/` to `/config/`. `tls.cache_dir` is always one of them (written as `/data/certs`): Let's Encrypt (`tls.mode: autocert`) keeps its certificates there, so fix it even if you only turn Let's Encrypt on later. +4. Install this app with **Appdata** pointing at that folder, and add back the variables from step 1. +5. For your books, either change the **Audiobooks** entry's container path to `/library` (where the old container mounted them), or keep `/audiobooks` and change the library's folder to `/audiobooks` in the admin console. + +Your users, progress and settings carry over. diff --git a/docs-users/getting-started/quickstart-docker.md b/docs-users/getting-started/quickstart-docker.md index 98644ea..2edb608 100644 --- a/docs-users/getting-started/quickstart-docker.md +++ b/docs-users/getting-started/quickstart-docker.md @@ -9,6 +9,10 @@ Docker is the recommended way to run AudioSilo on a NAS, home server or VPS. The The image is **`ghcr.io/kodestar/audiosilo-server`**. +:::tip On Unraid? +Install from Community Applications instead - see [Install on Unraid](./install-unraid.md). +::: + ### What you need - Docker with the Compose plugin (`docker compose`). diff --git a/docs-users/index.md b/docs-users/index.md index c3593c3..5f88ca4 100644 --- a/docs-users/index.md +++ b/docs-users/index.md @@ -18,7 +18,7 @@ AudioSilo is made of three pieces that work together. You only *have* to run the The heart of the system. It scans your audiobook folders, builds a fast search index, and streams the audio to your devices (new files show up when you browse to them or after a rescan). It also includes a built-in admin console for managing libraries, users and sharing, and it can serve the web player itself - so one running server is a complete, listen-in-the-browser setup. It is designed from the start to be safe to expose to the internet. -Install it with [Docker](./getting-started/quickstart-docker.md) or as a [single downloadable program](./getting-started/install-binary.md). +Install it with [Docker](./getting-started/quickstart-docker.md), from [Unraid's Community Applications](./getting-started/install-unraid.md), or as a [single downloadable program](./getting-started/install-binary.md). ### The player app @@ -38,7 +38,7 @@ An optional desktop app for the "librarian" side of things: setting up and conne ## How this guide is organized -- **[Getting started](./getting-started/quickstart-docker.md)** - install the server with [Docker](./getting-started/quickstart-docker.md) or a [native binary](./getting-started/install-binary.md), understand the [first run](./getting-started/first-run.md), lay out [your library folders](./getting-started/organizing-your-library.md), and set up [remote access](./getting-started/remote-access.md). +- **[Getting started](./getting-started/quickstart-docker.md)** - install the server with [Docker](./getting-started/quickstart-docker.md), [on Unraid](./getting-started/install-unraid.md) or as a [native binary](./getting-started/install-binary.md), understand the [first run](./getting-started/first-run.md), lay out [your library folders](./getting-started/organizing-your-library.md), and set up [remote access](./getting-started/remote-access.md). - **[Server administration](./admin/console-tour.md)** - the admin console: [libraries](./admin/libraries.md), [people and invites](./admin/users-and-invites.md), and [sharing parts of a library](./admin/sharing.md). - **[Listening](./listening/connecting.md)** - connecting a device, [browsing](./listening/browsing.md), [playing a book](./listening/playback.md), [the full player](./listening/full-player.md), [the companion](./listening/companion.md), the [sleep timer](./listening/sleep-timer.md), [Up next](./listening/up-next.md), [the end of a book](./listening/end-of-book.md), [offline downloads](./listening/offline-downloads.md), [your listening stats](./listening/you.md) and [year in listening](./listening/year-in-listening.md), [settings](./listening/settings.md), [your account](./listening/account.md), the [mobile apps](./listening/mobile-apps.md) and [keyboard shortcuts](./listening/keyboard-shortcuts.md). - **[Desktop manager](./manager/index.md)** - [managing servers](./manager/servers.md), [organizing and transferring books](./manager/organizing.md), and [backing up an Audible library](./manager/audible-backup.md). diff --git a/docs-users/manager/servers.md b/docs-users/manager/servers.md index 5c4fe58..ff86a97 100644 --- a/docs-users/manager/servers.md +++ b/docs-users/manager/servers.md @@ -155,6 +155,8 @@ path (e.g. `/mnt/cache/appdata/audiosilo`) so the database isn't on the slower user-share layer; the **library** can be any `/mnt/user` share. Files are written as `nobody:users`. Docker Compose is used if the Compose Manager plugin is installed, otherwise a plain container. + +To install by hand instead, use the LinuxServer.io app from Community Applications: see [Install on Unraid](../getting-started/install-unraid.md). ::: ### On a VPS (Hetzner) diff --git a/sidebars-users.ts b/sidebars-users.ts index 99af23b..80cd43b 100644 --- a/sidebars-users.ts +++ b/sidebars-users.ts @@ -11,6 +11,7 @@ const sidebars: SidebarsConfig = { collapsed: false, items: [ 'getting-started/quickstart-docker', + 'getting-started/install-unraid', 'getting-started/install-binary', 'getting-started/first-run', 'getting-started/organizing-your-library',