diff --git a/README.md b/README.md index bea6753..bd22a03 100644 --- a/README.md +++ b/README.md @@ -1,160 +1,236 @@ # assemblrr -> [!NOTE] -> **Developer’s note — vision & roadmap** -> assemblrr is infrastructure for self-hosted media *automation* (install, wire services, operate the stack). It does **not** provide media, indexers, or content. What you request, download, and host is entirely your responsibility and must comply with the laws that apply to you. -> -> Future directions and ideas shall be discussed with the community **[here](https://github.com/soulis-1256/assemblrr/discussions/1)** +> **Self-hosted media automation, set up in minutes — not a weekend.** -Self-hosted media automation, set up in minutes, not a weekend. +[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE) +[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20WSL2-orange.svg)](#installation) +[![Stack](https://img.shields.io/badge/Stack-Jellyfin%20%2B%20*arr-green.svg)](#the-stack) +[![Discussions](https://img.shields.io/github/discussions/soulis-1256/assemblrr)](https://github.com/soulis-1256/assemblrr/discussions) + +assemblrr is an automated setup and management suite for self-hosted media stacks. It provisions, wires, and maintains a complete ecosystem (media server, torrent client, indexers, request management, subtitles, and quality profiles) with zero manual work. + +[Features](#features) • [The Stack](#the-stack) • [Installation](#installation) • [CLI Usage](#cli-usage) • [Default Ports](#service-ports) • [Documentation](#documentation) • [Development](#development) + +--- ## Features -- **Guided Multi-Platform Install:** Interactive wizard for Linux or Windows (via WSL2). -- **Automated Service Wiring:** Automatically configures and connects Radarr, Sonarr, Prowlarr, qBittorrent, Bazarr, Seerr, Recyclarr, and Jellyfin post-install. -- **VPN-First Architecture:** Gluetun integration forces download client traffic through the VPN, complete with start-time verification and a stalled-routing watchdog. -- **Built-in Operator CLI:** Manage the stack (`start`, `stop`, `status`), edit configurations, snapshot backups, and update containers from the command line. -- **Optimized Media Layout:** Built-in hardlinks-friendly structure for Jellyfin with out-of-the-box TRaSH Guides quality profiles. +- **Guided Multi-Platform Setup:** Interactive installer for bare-metal Linux and Windows (via automated WSL2 bridging). +- **Automated Service Wiring:** Auto-configures and interconnects Radarr, Sonarr, Prowlarr, qBittorrent, Bazarr, Seerr, Recyclarr, and Jellyfin out of the box. +- **VPN-First Networking:** Built-in Gluetun integration routes download traffic through your VPN, complete with start-up validation and a stalled-routing watchdog. +- **Unified Operator CLI:** Manage the stack (`start`, `stop`, `restart`, `status`), change settings, take backups, and run updates directly from your terminal. +- **Hardlink-Optimized Storage:** Atomic moves and hardlink-friendly directory layout with automated TRaSH Guides quality profile sync via Recyclarr. +- **Granular Media Purge:** Single-command cleanup (`assemblrr purge`) that cleanly removes titles across *arr apps, the disk, and matching torrents simultaneously. -## The Stack (supported) +--- -Official support is the **express / default** install only: +## The Stack -- **Media Server:** Jellyfin -- **Download Client:** qBittorrent -- **Managers:** Sonarr, Radarr -- **Subtitles:** Bazarr (auto-wired to Sonarr/Radarr; optional OpenSubtitles.com) -- **Indexing:** Prowlarr -- **Request Management:** Seerr (`seerr-gateway`: delete request cancels in-flight downloads, not library files — see [docs/seerr-delete-request.md](docs/seerr-delete-request.md)) -- **Quality Profiles:** Recyclarr -- **VPN (optional):** Gluetun + watchdog -- **Management:** Built-in `assemblrr` CLI (`status`, `logs`, `start`/`stop`, …) +assemblrr provides an officially supported, fully-automated **express stack**: -Emby, Plex, Lidarr, SABnzbd, Portainer, Watchtower, and anything you add in `compose/custom.yaml` are **not officially supported**. They may exist as compose profiles or commented examples. Wiring, purge, upgrade, and bugfixes target the default stack above. +| Service | Category | Default Port | Description | +|---|---|---|---| +| **[Jellyfin](https://jellyfin.org/)** | Media Server | `8096` | Open-source media streaming platform | +| **[qBittorrent](https://www.qbittorrent.org/)** | Download Client | `8081` | Torrent client isolated behind VPN (or direct access) | +| **[Sonarr](https://sonarr.tv/)** | TV Management | `8989` | Smart PVR & series download automation | +| **[Radarr](https://radarr.video/)** | Movie Management | `7878` | Movie collection manager and automation | +| **[Prowlarr](https://prowlarr.com/)** | Indexer Sync | `9696` | Centralized indexer proxy syncing to *arr apps | +| **[Seerr](https://github.com/seerr-team/seerr)** | Request Management | `5055` | Media discovery and user request gateway | +| **[Bazarr](https://www.bazarr.media/)** | Subtitles | `6767` | Automatic subtitle downloader for Sonarr and Radarr | +| **[Recyclarr](https://recyclarr.dev/)** | Quality Profiles | — | Syncs recommended TRaSH Guides quality profiles & custom formats | +| **[Gluetun](https://github.com/qdm12/gluetun)** *(Optional)* | VPN & Killswitch | — | Secure VPN tunnel with health watchdog for download traffic | + +> [!TIP] +> **Custom & Extended Services:** You can easily add custom containers (e.g. Plex, Emby, SABnzbd, Portainer) via `compose/custom.yaml` or optional compose profiles. Official automated wiring and CLI maintenance workflows target the core stack above. + +--- ## Installation ### Linux / WSL2 -*Note: `bash` must be installed to run the setup script.* - -bash / zsh: +Run the one-line bootstrap installer in your terminal (requires `bash` and `curl`): ```bash bash <(curl -fsSL https://raw.githubusercontent.com/soulis-1256/assemblrr/main/platform/linux/bootstrap.sh) ``` -fish (no `<(...)` process substitution — use `psub` instead): - -```fish -bash (curl -fsSL https://raw.githubusercontent.com/soulis-1256/assemblrr/main/platform/linux/bootstrap.sh | psub) -``` - -Install a branch or tag (always curl bootstrap from `main`; pass the ref to the installer): - -```bash -bash <(curl -fsSL https://raw.githubusercontent.com/soulis-1256/assemblrr/main/platform/linux/bootstrap.sh) --ref dev -# or: ASSEMBLRR_REF=dev bash <(curl -fsSL https://raw.githubusercontent.com/soulis-1256/assemblrr/main/platform/linux/bootstrap.sh) -``` - -```fish -bash (curl -fsSL https://raw.githubusercontent.com/soulis-1256/assemblrr/main/platform/linux/bootstrap.sh | psub) --ref dev -``` - -Already installed? Use `assemblrr upgrade` or `assemblrr uninstall` — do not run the bootstrap again. - ### Windows (PowerShell) -Ensure Docker Desktop is running before execution. +Ensure Docker Desktop is running, then launch PowerShell as Administrator and run: ```powershell irm https://raw.githubusercontent.com/soulis-1256/assemblrr/main/platform/windows/bootstrap.ps1 | iex ``` -Install a branch or tag: +> [!NOTE] +> The Windows installer automatically bridges the stack into your default WSL2 Linux distribution. +### Advanced Options + +#### Fish Shell + +```fish +bash (curl -fsSL https://raw.githubusercontent.com/soulis-1256/assemblrr/main/platform/linux/bootstrap.sh | psub) +``` + +#### Custom Branch or Tag + +**Linux / WSL2:** +```bash +bash <(curl -fsSL https://raw.githubusercontent.com/soulis-1256/assemblrr/main/platform/linux/bootstrap.sh) --ref dev +# or: +ASSEMBLRR_REF=dev bash <(curl -fsSL https://raw.githubusercontent.com/soulis-1256/assemblrr/main/platform/linux/bootstrap.sh) +``` + +**Windows (PowerShell):** ```powershell $env:ASSEMBLRR_REF = "dev"; irm https://raw.githubusercontent.com/soulis-1256/assemblrr/main/platform/windows/bootstrap.ps1 | iex ``` -## Usage (CLI) +> [!IMPORTANT] +> **Already installed?** Use `assemblrr upgrade` to update or `assemblrr uninstall` to remove. Do not re-run the bootstrap script on an existing installation. -After install, the CLI is on your `PATH` as `assemblrr`. Run `assemblrr `: +--- + +## CLI Usage + +Once installed, the `assemblrr` command-line interface is available on your system `PATH`: + +```bash +assemblrr [options] +``` + +### Stack Control | Command | Description | |---|---| -| `start` | Start all services (with VPN verification) | -| `stop` | Stop all services | -| `restart` | Restart all services | -| `status` | Operator dashboard: service state + URLs (`--docker` for raw compose ps) | -| `health` | Compact healthcheck pass/fail for all containers | -| `logs [service]` | Follow logs (all services, or one) | -| `config` | List config subcommands | -| `config show` | Show current configuration | -| `config apply` | Re-wire running services (no compose replace). Alias: `config wire` | -| `config edit` | Pick a setting to change (indexers, login, VPN, …) | -| `backup /target/dir` | Snapshot configuration | -| `restore /backup.tar.gz` | Restore from a backup archive | -| `update-containers` | Pull latest images and restart (offers a backup first) | -| `upgrade` | Upgrade from git `main` (or `--from DIR`): files, migrations, stack restart, service wiring | -| `upgrade --skip-stack` | Apply files and CLI without restarting containers | -| `upgrade --check` | Dry-run: show which managed files and migrations would run | -| `check-vpn` | Poll VPN health | -| `purge` | Delete one title (*arr + library folder + matching qB torrent). TV can be season-scoped | -| `uninstall` | Remove everything (asks before deleting data) | +| `assemblrr start [service]` | Start all services (or a specific service) with VPN verification | +| `assemblrr stop [service]` | Stop all running services (or a specific service) | +| `assemblrr restart [service]` | Restart all services (or a specific service) | +| `assemblrr destroy [service]` | Teardown and reset container state | +### Status & Inspection -## Configuration & Architecture +| Command | Description | +|---|---| +| `assemblrr status` | Operator dashboard displaying service states, health, and access URLs | +| `assemblrr status --docker` | Raw `docker compose ps` output | +| `assemblrr health` | Compact health check pass/fail summary for all containers | +| `assemblrr logs [service]` | Tail and follow logs for all containers or a specific service | +| `assemblrr check-vpn` | Verify VPN connectivity, assigned IP, and tunnel health | -Configuration lives in your installation directory (default: `~/assemblrr`). +### Configuration & Wiring -- `.env`: Generated at install from [`.env.example`](.env.example) (all variables are documented there). Credentials live under `secrets/`, not in `.env`. -- `compose/base.yaml`: Core services. -- `compose/vpn.yaml` / `compose/direct-access.yaml`: Networking overlays. -- `compose/custom.yaml`: Optional services (from the example under `compose/examples/`). -- `config/`: Persistent service data. +| Command | Description | +|---|---| +| `assemblrr config` | List all available configuration options | +| `assemblrr config show` | Display active environment configuration | +| `assemblrr config edit` | Interactive wizard to update settings (VPN, indexers, credentials, etc.) | +| `assemblrr config apply` | Re-run automated service wiring (alias: `config wire`) | + +### Maintenance, Backups & Cleanup + +| Command | Description | +|---|---| +| `assemblrr backup ` | Create a timestamped configuration backup archive | +| `assemblrr restore ` | Restore configuration from a backup archive | +| `assemblrr update-containers` | Pull the latest Docker images and restart the stack (prompts for backup first) | +| `assemblrr upgrade` | Upgrade assemblrr core scripts, apply migrations, and update wiring | +| `assemblrr upgrade --check` | Dry-run: preview upcoming file changes and migrations | +| `assemblrr upgrade --skip-stack`| Apply CLI and script updates without restarting running containers | +| `assemblrr purge` | Delete a title across Sonarr/Radarr, filesystem, and active qBittorrent torrents | +| `assemblrr uninstall` | Cleanly remove the entire stack (preserves media unless `--media` is passed) | + +--- + +## Service Ports + +When running the default stack, the following ports are mapped on `http://localhost:`: + +| Service | Port | Default URL | Purpose | +|---|---|---|---| +| **Jellyfin** | `8096` | `http://localhost:8096` | Media streaming frontend | +| **qBittorrent** | `8081` | `http://localhost:8081` | Torrent Web UI | +| **Sonarr** | `8989` | `http://localhost:8989` | TV show manager | +| **Radarr** | `7878` | `http://localhost:7878` | Movie collection manager | +| **Prowlarr** | `9696` | `http://localhost:9696` | Indexer management | +| **Seerr** | `5055` | `http://localhost:5055` | Media request portal (via gateway) | +| **Bazarr** | `6767` | `http://localhost:6767` | Subtitle manager | + +--- + +## Configuration & Layout + +Configuration and persistent state live in your installation directory (default: `~/assemblrr`): + +```text +~/assemblrr/ +├── .env # Environment variables generated during setup (see .env.example) +├── secrets/ # Authenticated credentials and VPN keys (kept separate from .env) +├── compose/ +│ ├── base.yaml # Core service definitions +│ ├── vpn.yaml # VPN network overlay (Gluetun) +│ ├── direct-access.yaml# Direct networking overlay (non-VPN) +│ └── custom.yaml # User-defined custom services +├── config/ # Persistent database and appdata for all services +└── scripts/ # Internal watchdog and gateway sidecar scripts +``` + +--- ## Documentation -- **[TRaSH Guides & Quality Profiles](docs/trash-guides.md):** Details on how assemblrr handles quality profiles and what to do when community guide IDs change. -- **[Seerr delete request](docs/seerr-delete-request.md):** How `seerr-gateway` cancels in-flight downloads on “delete request” (library files stay), and how to retire it if Seerr gains this natively. -- **[Uninstall Guide](docs/uninstall.md):** Complete removal guide, including a full inventory of what an installation creates. -- **[API Reference](docs/api-reference.md):** Official API documentation links for all services in the stack. +- **[TRaSH Guides & Quality Profiles](docs/trash-guides.md):** Quality profile synchronization and custom format handling. +- **[Seerr Delete Request](docs/seerr-delete-request.md):** In-flight download cancellation workflow and gateway architecture. +- **[Uninstall Guide](docs/uninstall.md):** Complete removal walkthrough and resource inventory. +- **[API Reference](docs/api-reference.md):** Upstream API endpoints and integration notes. + +--- ## Development -### Windows (powershell) - -```powershell -git clone https://github.com/soulis-1256/assemblrr.git -cd assemblrr -.\platform\windows\bootstrap-dev.ps1 -Full # Full setup (copies files to WSL2 and runs setup.sh) -.\platform\windows\bootstrap-dev.ps1 -Full -Clean # Uninstalls the existing installation, then does a full setup -.\platform\windows\bootstrap-dev.ps1 -Update # Sync changed files to WSL2 (no setup re-run, useful for cli changes) -``` - -### Linux/WSL2 +### Setting Up a Development Environment +**Linux / WSL2:** ```bash git clone https://github.com/soulis-1256/assemblrr.git cd assemblrr bash bin/setup.sh ``` -### Tests - -```bash -make test # unit + compose config + shellcheck (if installed) -make test-unit # pure shell unit tests (no Docker) -make test-compose # docker compose config validation -make test-integration # live qBittorrent + vpn-watchdog (opt-in) +**Windows (PowerShell):** +```powershell +git clone https://github.com/soulis-1256/assemblrr.git +cd assemblrr +.\platform\windows\bootstrap-dev.ps1 -Full # Full setup (copies files to WSL2 and runs setup.sh) +.\platform\windows\bootstrap-dev.ps1 -Full -Clean # Clean install (uninstalls previous setup first) +.\platform\windows\bootstrap-dev.ps1 -Update # Fast sync for local script/CLI edits ``` -Live integration mutates a running stack — requires `ASSEMBLRR_ALLOW_LIVE_TEST=1`. See [tests/README.md](tests/README.md). +### Running Tests -## Acknowledgments +```bash +make test # Run all unit tests, compose validation, and shellcheck +make test-unit # Pure shell unit tests (no Docker required) +make test-compose # Docker Compose syntax and configuration validation +make test-integration # Live integration tests (requires ASSEMBLRR_ALLOW_LIVE_TEST=1) +make lint # Run shellcheck on all scripts +``` -Originally inspired by [YAMS](https://yams.media/) ([rogsme/yams](https://github.com/rogsme/yams)); assemblrr has since been rewritten and expanded into its own project. +See [tests/README.md](tests/README.md) for testing guidelines and environment flags. -### License -GNU General Public License v3.0 +--- + +## Community & Legal + +assemblrr is infrastructure automation tooling designed to wire together and manage self-hosted applications. It does not provide, index, host, or distribute media content. Users are solely responsible for complying with applicable laws and licensing regulations in their jurisdiction. + +Join discussions, request features, and connect with the community on **[GitHub Discussions](https://github.com/soulis-1256/assemblrr/discussions)**. + +--- + +## Acknowledgments & License + +- Originally inspired by [YAMS](https://yams.media/) ([rogsme/yams](https://github.com/rogsme/yams)); assemblrr has since been completely re-architected and expanded into an independent platform. +- Licensed under the **[GNU General Public License v3.0](LICENSE)**.