mirror of
https://github.com/soulis-1256/assemblrr.git
synced 2026-10-14 03:58:22 +00:00
docs: overhaul and restructure README
- Add project badges and quick-navigation links - Categorize CLI commands into functional groups - Add default service ports table and directory layout - Streamline installation steps and format advanced options - Refine tone across stack, features, and legal sections
This commit is contained in:
soulis-1256
parent
2ca21c6b01
commit
c7d9ff1648
1 changed files with 178 additions and 102 deletions
280
README.md
280
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)
|
||||
[](#installation)
|
||||
[](#the-stack)
|
||||
[](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 <command>`:
|
||||
---
|
||||
|
||||
## CLI Usage
|
||||
|
||||
Once installed, the `assemblrr` command-line interface is available on your system `PATH`:
|
||||
|
||||
```bash
|
||||
assemblrr <command> [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 <path>` | Create a timestamped configuration backup archive |
|
||||
| `assemblrr restore <file.tar.gz>` | 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:<PORT>`:
|
||||
|
||||
| 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)**.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue