Updated README.md

2025-09-21 22:18:04 +00:00
parent 3dfdefe33a
commit a4c6014275
1 changed files with 154 additions and 43 deletions
--- a/README.md
+++ b/README.md
@@ -1,71 +1,182 @@
-Maloja-Lidarr Importer
+# Maloja → Lidarr Importer
 🎯 Overview
 This project provides a simple API service that syncs your listening history from a self-hosted Maloja instance to a Lidarr custom import list.
-Lidarr's custom import feature requires a JSON list of MusicBrainz Artist IDs. This service automatically fetches your unique artists from Maloja and serves them in the correct format, allowing Lidarr to add new artists to your library automatically.
+## 🎯 Overview
 A small API service that syncs listening history from a self-hosted **Maloja** instance and exposes a JSON list of **MusicBrainz Artist IDs** suitable for Lidarr's *Custom Import* feature. The service periodically fetches unique artists from Maloja, resolves MusicBrainz IDs where needed, and serves them for automatic import into Lidarr.
-✨ Features
+---
 Automatic Synchronization: Fetches and updates the list of artists from your Maloja instance every hour.
-MusicBrainz Integration: Resolves artist IDs even when a MusicBrainz ID for a track isn't available.
+## ✨ Features
 - **Automatic sync**: fetches and updates artist lists on a schedule (configurable).  
 - **MusicBrainz resolution**: resolves artist MBIDs even if individual tracks lack them.  
 - **Docker-ready**: pull and run a pre-built image — no local build required.  
 - Lightweight and easy to integrate with Lidarr's import lists.
-Docker-Ready: Packaged as a lightweight Docker image for easy deployment.
+---
-📦 Prerequisites
+## 📦 Prerequisites
-Docker and Docker Compose
+- Docker & Docker Compose (v2 recommended)  
 - A running Maloja instance with API access enabled  
 - A running Lidarr instance (on same Docker network or reachable from the importer)
-A Maloja instance with API access enabled
+---
-A Lidarr instance
+## 🚀 Quick Start (pull the hosted image)
-🚀 Getting Started
+1. Copy the sample environment template and edit it:
 1. Clone the Repository
 Bash
 git clone https://gitea.kansaigaijin.com/kansaigaijin/Majola-Lidarr-Importer.git
 cd Majola-Lidarr-Importer
 2. Configure Environment Variables
 Copy the provided .env.template file to a new file named .env and fill in your Maloja API details.
 Bash
 ```bash
 cp .env.template .env
-Open the .env file with a text editor and enter your specific values.
+# edit .env and set SOURCE_API_URL and SOURCE_API_KEY at minimum
 ```
-Ini, TOML
+2. Edit `docker-compose.yml` (example shown below) to point `image:` to your hosted image (replace `IMAGE_NAME`).
 3. Pull the image and start the container:
 ```bash
 docker compose pull
 docker compose up -d
 ```
 > If you want to make sure Compose does not try to build anything locally:
 >
 > ```bash
 > docker compose up -d --no-build
 > ```
 ---
 ## ⚙️ Example `.env.template`
 ```ini
 # Maloja API details
 # Get these from your Maloja instance settings
 SOURCE_API_URL=https://<your-maloja-url>/apis/mlj_1/scrobbles
 SOURCE_API_KEY=<your_api_key>
 3. Run with Docker Compose
 To start the service, simply run the following command in the project's root directory:
-Bash
+# Service settings
 LISTEN_HOST=0.0.0.0
 LISTEN_PORT=5000
-docker-compose up -d
+# Poll interval in minutes (how often Maloja is queried)
-This command will pull the pre-built Docker image and start the container in the background.
+POLL_INTERVAL_MINUTES=60
-🎶 Lidarr Setup
+# Logging: DEBUG, INFO, WARNING, ERROR
-In Lidarr, navigate to Settings -> Import Lists.
+LOG_LEVEL=INFO
 ```
-Click the + button to add a new list.
+---
-Select Custom from the list of providers.
+## 🐳 Example `docker-compose.yml`
-Configure the settings as follows:
+Replace `IMAGE_NAME` with your hosted image (for example: `ghcr.io/youruser/maloja-lidarr-importer:latest`).
-Name: Maloja List (or a name of your choice)
+```yaml
 version: "3.8"
-Tags: (Optional, add a tag like maloja)
+services:
  maloja-lidarr-importer:
    image: IMAGE_NAME
    container_name: maloja-lidarr-importer
    restart: unless-stopped
    env_file: .env
    ports:
      - "5000:5000"    # optional: expose if you need external access; omit to keep internal only
    networks:
      - appnet
-Url: http://maloja-lidarr-importer-api:5000/artists
+networks:
  appnet:
    driver: bridge
 ```
-Minimum Time: 60 Minutes (or more)
+- If Lidarr runs in Docker on the same `appnet` network, use the service name as hostname (see Lidarr setup below).
 - If you prefer not to expose port 5000 externally, remove the `ports:` mapping and keep communication internal to your Docker network.
-Password: (Leave blank)
+---
-This URL uses Docker's internal networking to allow Lidarr to communicate directly with the API container, bypassing any external authentication proxies or firewalls.
+## 🎶 Lidarr Setup
 1. In Lidarr: **Settings → Import Lists**.  
 2. Click **+** to add a new list. Choose **Custom** provider.  
 3. Configure:
-📄 License
+- **Name**: `Maloja List` (or any name)  
-This project is licensed under the MIT License.
+- **Tags**: optional (e.g. `maloja`)  
 - **URL**:  
  - If both services are on the same Docker network:  
    ```
    http://maloja-lidarr-importer:5000/artists
    ```
    *(Use the service name you used in `docker-compose.yml` as hostname.)*
  - If the importer is exposed externally (host port):  
    ```
    http://<host-or-domain>:5000/artists
    ```
 - **Minimum Time**: `60 Minutes` (or as you prefer)  
 - **Password**: leave blank (unless you've added authentication via a reverse proxy)
 Save and enable the list. Lidarr will poll the URL on its schedule and import new artists present in the JSON array.
 ---
 ## 🔌 API Endpoints
 - `GET /artists`  
  - Returns a JSON array of MusicBrainz Artist IDs optimized for Lidarr custom import:
    ```json
    [
      "b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d",
      "some-other-mbid-..."
    ]
    ```
  - (Lidarr expects a simple array of MBIDs.)
 - `GET /health` (optional)  
  - Returns basic service health/status (if implemented) — check for `200 OK`.
 > If your running container exposes additional endpoints (metrics, debug), document them here.
 ---
 ## 🪲 Logs & Troubleshooting
 - View logs:
  ```bash
  docker compose logs -f maloja-lidarr-importer
  ```
 - Common issues:
  - **Empty list in Lidarr**: check `.env` values and logs for Maloja API errors (401/403/404).  
  - **Lidarr can't reach URL**: if using Docker internal hostname, both containers must share a network. If using host exposure, confirm port mapping and firewall.  
  - **CORS / Proxy**: If you run a reverse proxy in front of the importer, ensure `GET /artists` is forwarded and not blocked by auth. For public exposure, consider adding basic auth or IP restrictions at the proxy.
  - **MusicBrainz resolution failures**: look for log warnings indicating failed lookups; a short retry or increased `POLL_INTERVAL_MINUTES` may help.
 ---
 ## 🛡 Security Notes
 - Do not publicly expose the `/artists` endpoint unless behind a reverse proxy or IP restriction if your Maloja or import lists contain sensitive info.
 - Use HTTPS/secure proxy in production.
 - If you add authentication at the proxy layer, configure Lidarr to include credentials or use a private network.
 ---
 ## 🧰 Deployment tips
 - For a single-host Docker setup, the compose example is sufficient.  
 - For Kubernetes or other orchestrators, convert the compose file to equivalent manifests and mount `.env` as secrets/configmaps where needed.  
 - Use a small monitoring probe that checks `/health` and restarts the container on failures.
 ---
 ## 🤝 Contributing
 Contributions welcome. Please:
 - Open an issue for bugs or feature requests.
 - Fork the repo, make changes on a topic branch, and submit a PR with a clear description.
 - Follow existing code style and add tests for non-trivial logic.
 ---
 ## 📜 License
 This project is provided under the **MIT License** — see `LICENSE` for details.
 ---
 ## Contact / Support
 If you hit an issue or would like a feature, open an issue in the repo or contact the maintainer listed in commit metadata.