diff --git a/README.md b/README.md index 482b976..29b8ca7 100644 --- a/README.md +++ b/README.md @@ -1,90 +1,90 @@ -# MBID Poller - -This project provides a polling mechanism, packaged in a **Docker container**, to routinely check the MusicBrainz ID (MBID) status for items and then optionally trigger a search in a **Lidarr** instance. - ---- - -## 💡 Acknowledgements - -The core logic for the polling mechanism in this project is based on an existing script generously shared by GitHub user **kchiem**. - -We are utilizing and adapting the Perl script found in the following public Gist: - -* **Original Script:** `kchiem/lidarr-ping.dist` -* **Link:** https://gist.github.com/kchiem/eb998ac3c6f5a96cbec03b8e8c3b21a6 - -We appreciate kchiem's contribution to the community! - ---- - -## 🚀 Setup and Usage - -This project is designed to run as a service alongside a **Lidarr** instance using Docker Compose. - -### 1. Prerequisites - -Before starting, ensure you have: - -1. **Docker** and **Docker Compose** installed. -2. A running **Lidarr** instance. -3. The project files (`Dockerfile`, `poller.pl`, `docker-compose.yaml`, etc.) in a single directory. - -### 2. Configure Docker Compose - -The `mbid-poller` container needs to communicate with your Lidarr instance. - -1. **Rename the Example:** Rename the provided `docker-compose.yaml.example` to `docker-compose.yaml`. -2. [cite_start]**Network Setup:** Ensure the `lidarr` and `mbid-poller` services are on the **same Docker network** (e.g., `example_network`)[cite: 4, 5]. If you use a different setup (like host network), update `LIDARR_BASE` accordingly. -3. [cite_start]**Lidarr Base URL:** Verify the `LIDARR_BASE` environment variable in the `mbid-poller` service points to your Lidarr instance[cite: 5]. - - ```yaml - # Example for the default setup: - - LIDARR_BASE=http://lidarr:8686 - ``` - -### 3. Choose the MBID Input Source - -[cite_start]The `poller.pl` script supports three different ways to provide MBIDs, in order of priority[cite: 5, 6]: - -| Environment Variable | Priority | Description | -| :--- | :--- | :--- | -| `MBID_API_URL` | **1st** (Highest) | A URL that returns a JSON array of objects, each containing a `foreignId` field. | -| `MBID_JSON_FILE` | **2nd** | A path to a local JSON file (like `ids.json`) containing the MBID array. | -| `MBID_URL` | **3rd** (Lowest) | A single MusicBrainz URL or ID to process. | - -[cite_start]In your `docker-compose.yaml`, **only one** of these should be uncommented and set[cite: 5, 6, 7]. - -#### A. Using a JSON File (Recommended for simple setups) - -1. [cite_start]Place your list of IDs in an `ids.json` file in the project directory (or adjust the volume mount)[cite: 7]. -2. In `docker-compose.yaml`, **comment out** `MBID_API_URL` and **uncomment** `MBID_JSON_FILE`: - - ```yaml - # ... mbid-poller environment section - environment: - # ... - - LIDARR_BASE=http://lidarr:8686 - # - MBID_API_URL= - - MBID_JSON_FILE=/config/ids.json - # - MBID_URL=... - volumes: - - ./ids.json:/config/ids.json:ro # Maps your local file into the container - ``` - -### 4. Build and Run - -With your files and `docker-compose.yaml` configured, you can build and run the poller. - -1. [cite_start]**Build the Container:** This compiles the Perl dependencies using the `Dockerfile`[cite: 1, 2, 3]. - - ```bash - docker compose build mbid-poller - ``` - -2. [cite_start]**Run the Poller:** Since the `restart` policy is set to `"no"`[cite: 7], this command will run the script once and exit. - - ```bash - docker compose up mbid-poller - ``` - +# MBID Poller + +This project provides a polling mechanism, packaged in a **Docker container**, to routinely check the MusicBrainz ID (MBID) status for items and then optionally trigger a search in a **Lidarr** instance. + +--- + +## 💡 Acknowledgements + +The core logic for the polling mechanism in this project is based on an existing script generously shared by GitHub user **kchiem**. + +We are utilizing and adapting the Perl script found in the following public Gist: + +* **Original Script:** `kchiem/lidarr-ping.dist` +* **Link:** https://gist.github.com/kchiem/eb998ac3c6f5a96cbec03b8e8c3b21a6 + +We appreciate kchiem's contribution to the community! + +--- + +## 🚀 Setup and Usage + +This project is designed to run as a service alongside a **Lidarr** instance using Docker Compose. + +### 1. Prerequisites + +Before starting, ensure you have: + +1. **Docker** and **Docker Compose** installed. +2. A running **Lidarr** instance. +3. The project files (`Dockerfile`, `poller.pl`, `docker-compose.yaml`, etc.) in a single directory. + +### 2. Configure Docker Compose + +The `mbid-poller` container needs to communicate with your Lidarr instance. + +1. **Rename the Example:** Rename the provided `docker-compose.yaml.example` to `docker-compose.yaml`. +2. **Network Setup:** Ensure the `lidarr` and `mbid-poller` services are on the **same Docker network** (e.g., `example_network`). If you use a different setup (like host network), update `LIDARR_BASE` accordingly. +3. **Lidarr Base URL:** Verify the `LIDARR_BASE` environment variable in the `mbid-poller` service points to your Lidarr instance. + + ```yaml + # Example for the default setup: + - LIDARR_BASE=http://lidarr:8686 + ``` + +### 3. Choose the MBID Input Source + +The `poller.pl` script supports three different ways to provide MBIDs, in order of priority: + +| Environment Variable | Priority | Description | +| :--- | :--- | :--- | +| `MBID_API_URL` | **1st** (Highest) | A URL that returns a JSON array of objects, each containing a `foreignId` field. | +| `MBID_JSON_FILE` | **2nd** | A path to a local JSON file (like `ids.json`) containing the MBID array. | +| `MBID_URL` | **3rd** (Lowest) | A single MusicBrainz URL or ID to process. | + +In your `docker-compose.yaml`, **only one** of these should be uncommented and set. + +#### A. Using a JSON File (Recommended for simple setups) + +1. Place your list of IDs in an `ids.json` file in the project directory (or adjust the volume mount). +2. In `docker-compose.yaml`, **comment out** `MBID_API_URL` and **uncomment** `MBID_JSON_FILE`: + + ```yaml + # ... mbid-poller environment section + environment: + # ... + - LIDARR_BASE=http://lidarr:8686 + # - MBID_API_URL= + - MBID_JSON_FILE=/config/ids.json + # - MBID_URL=... + volumes: + - ./ids.json:/config/ids.json:ro # Maps your local file into the container + ``` + +### 4. Build and Run + +With your files and `docker-compose.yaml` configured, you can build and run the poller. + +1. **Build the Container:** This compiles the Perl dependencies using the `Dockerfile`. + + ```bash + docker compose build mbid-poller + ``` + +2. **Run the Poller:** Since the `restart` policy is set to `"no"`, this command will run the script once and exit. + + ```bash + docker compose up mbid-poller + ``` + The script will fetch the IDs, then loop through them, pinging the external MusicBrainz API until a successful response is received. It then outputs a Lidarr search URL for you to manually or automatically trigger the import in Lidarr. \ No newline at end of file