Update README.md

Corrected the expected output of the JSON from the API

.env.backup

@@ -1,2 +0,0 @@
-SOURCE_API_URL=https://maloja.kansaigaijin.com/apis/mlj_1/scrobbles
-SOURCE_API_KEY=MeEpNNVgLb9nB8OPbgtKjxn5jo1l8KLYTLyWvWBs48WLTij0BaYNSXtJY0UMa8

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.
+## 🎯 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.
-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.
+
-
+---
-Features
+
-Automatic Synchronization: Fetches and updates the list of artists from your Maloja instance every hour.
+## ✨ Features
-
+- **Automatic sync**: fetches and updates artist lists on a schedule (configurable).  
-MusicBrainz Integration: Resolves artist IDs even when a MusicBrainz ID for a track isn't available.
+- **MusicBrainz resolution**: resolves artist MBIDs even if individual tracks lack them.  
-
+- **Docker-ready**: pull and run a pre-built image — no local build required.  
-Docker-Ready: Packaged as a lightweight Docker image for easy deployment.
+- Lightweight and easy to integrate with Lidarr's import lists.
-
+
-Prerequisites
+---
-Docker and Docker Compose
+
-
+## 📦 Prerequisites
-A Maloja instance with API access enabled
+- Docker & Docker Compose (v2 recommended)  
-
+- A running Maloja instance with API access enabled  
-A Lidarr instance
+- A running Lidarr instance (on same Docker network or reachable from the importer)
-
+
-Getting Started
+---
-1. Clone the Repository
+
-Bash
+## 🚀 Quick Start (pull the hosted image)
-
+
-git clone https://gitea.kansaigaijin.com/kansaigaijin/Majola-Lidarr-Importer.git
+1. Copy the sample environment template and edit it:
-cd Majola-Lidarr-Importer
+
-2. Configure Environment Variables
+```bash
-Copy the provided .env.template file to a new file named .env and fill in your Maloja API details.
+cp .env.template .env
-
+# edit .env and set SOURCE_API_URL and SOURCE_API_KEY at minimum
-Bash
+```
-
+
-cp .env.template .env
+2. Edit `docker-compose.yml` (example shown below) to point `image:` to your hosted image (replace `IMAGE_NAME`).
-Open the .env file with a text editor and enter your specific values.
+
-
+3. Pull the image and start the container:
-Ini, TOML
+
-
+```bash
-# Maloja API details
+docker compose pull
-# Get these from your Maloja instance settings
+docker compose up -d
-SOURCE_API_URL=https://<your-maloja-url>/apis/mlj_1/scrobbles
+```
-SOURCE_API_KEY=<your_api_key>
+
-3. Run with Docker Compose
+> If you want to make sure Compose does not try to build anything locally:
-To start the service, simply run the following command in the project's root directory:
+>
-
+> ```bash
-Bash
+> docker compose up -d --no-build
-
+> ```
-docker-compose up -d
+
-This command will build the Docker image (if you're using the build directive) and start the container in the background.
+---
-
+
-Lidarr Setup
+## ⚙️ Example `.env.template`
-In Lidarr, go to Settings -> Import Lists.
+
-
+```ini
-Click the + button to add a new list.
+# Maloja API details
-
+SOURCE_API_URL=https://<your-maloja-url>/apis/mlj_1/scrobbles
-Select Custom from the list of providers.
+SOURCE_API_KEY=<your_api_key>
-
+
-Configure the settings as follows:
+# Service settings
-
+LISTEN_HOST=0.0.0.0
-Name: Maloja List (or a name of your choice)
+LISTEN_PORT=5000
-
+
-Tags: (Optional, add a tag like maloja)
+# Poll interval in minutes (how often Maloja is queried)
-
+POLL_INTERVAL_MINUTES=60
-Url: http://maloja-lidarr-importer-api:5000/artists
+
-
+# Logging: DEBUG, INFO, WARNING, ERROR
-Minimum Time: 60 Minutes (or more)
+LOG_LEVEL=INFO
-
+```
-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.
+
-
+## 🐳 Example `docker-compose.yml`
-License
+
-This project is licensed under the MIT License. See the LICENSE file for details.
+Replace `IMAGE_NAME` with your hosted image (for example: `ghcr.io/youruser/maloja-lidarr-importer:latest`).
+
+```yaml
+version: "3.8"
+
+services:
+  maloja-lidarr-importer:
+    image: gitea.kansaigaijin.com/KansaiGaijin/Majola-Lidarr-Importer:latest
+    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
+
+networks:
+  appnet:
+    driver: bridge
+```
+
+- 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.
+
+---
+
+## 🎶 Lidarr Setup
+1. In Lidarr: **Settings → Import Lists**.  
+2. Click **+** to add a new list. Choose **Custom** provider.  
+3. Configure:
+
+- **Name**: `Maloja List` (or any name)  
+- **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 dictionaries, each containing a `foreignId` field with a MusicBrainz Artist ID.  
+    ```json
+    [
+      {"foreignId": "0b987f3c-7264-439a-a1b9-62a69c9b1d91"},
+      {"foreignId": "0ebdc5f5-0a11-415a-b6f3-efe0d36c6e9d"}
+    ]
+    ```
+  - Lidarr expects objects with a `foreignId` key pointing to the MBID.
+
+- `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.

docker-compose.yml

@@ -1,6 +1,6 @@
 services:
-  lidarr-importer-api:
+  api:
-    image: gitea.kansaigaijin.com/kansaigaijin/majola-lidarr-importer:latest
+    build: .
     container_name: maloja-lidarr-importer-api
     volumes:
       - ./logs:/app/logs