Fetcharr

To allow other plugins to consume your custom API, follow these two steps:

1. Export your classes: Add the relevant classes or packages to the exports list in your plugin's plugin.yaml. This makes them available in other plugins' ClassLoaders.
2. Register your API: Use the me.egg82.fetcharr.api.model.registry.Registry class via the FetcharrAPIProvider to register your service.

Consuming an API: Other plugins can retrieve your registered API using:

• FetcharrAPIProvider.instance().registry().getFirst()
• FetcharrAPIProvider.instance().registry().getAll()

Best Practice: Only export necessary API interfaces to avoid namespace pollution; do not export implementation details.

// Registering an API
FetcharrAPIProvider.instance().registry().register(yourApiInstance);

// Consuming an API (in another plugin)
var api = FetcharrAPIProvider.instance().registry().getFirst();

Fetcharr supports both file-based and in-memory caching. You can control this using USE_FILE_CACHE and USE_MEMORY_CACHE with values auto, true, or false.

Automatic Configuration (auto mode)

• USE_FILE_CACHE=auto: Fetcharr checks if the configured CACHE_DIR is writable. If writable, file caching is enabled; otherwise, it is disabled.
• USE_MEMORY_CACHE=auto: Fetcharr checks if file caching is usable. If file caching is active, in-memory caching is disabled to save RAM. If file caching is unavailable, in-memory caching is enabled.

Key Considerations

• Preference: File caching is preferred over in-memory caching because in-memory caching can consume significant amounts of RAM.
• Persistence: If you use purely in-memory caching, your cache will be lost whenever the container restarts.
• Impact: Disabling or clearing the cache will not break the program, but it will result in more API calls and slower execution speeds.

Use this docker-compose.yml structure to manage your Fetcharr deployment. Ensure you provide the necessary environment variables for your specific '*arr' instances and map the required volumes.

services:
  fetcharr:
    image: egg82/fetcharr:latest
    container_name: fetcharr
    hostname: fetcharr
    environment:
      - VERIFY_CERTS=true
      - SSL_PATH=/etc/ssl/certs/ca-bundle.crt
      - SEARCH_AMOUNT=5
      - SEARCH_INTERVAL=1hour
      - RADARR_0_URL=https://radarr.home.lab
      - RADARR_0_API_KEY=e8ea891d72ff973fa6db0d34369a60a7
      - SONARR_0_URL=https://sonarr.home.lab
      - SONARR_0_API_KEY=71730b5dfaa4293fe0c050844c10df66
      - SONARR_1_URL=https://anime.home.lab
      - SONARR_1_API_KEY=bdb84dc8e4b787c76be8aae2dfe9bd19
    volumes:
      - ./config:/app/config
      - ./cache:/app/cache
      - ./logs:/app/logs
      - ./plugins:/app/plugins
    restart: unless-stopped

By default, Fetcharr runs as UID 1000 and GID 1000. You have two methods for changing the user:

1. Runtime User Setting: Set the user directly via the --user flag in Docker or the user key in Compose. Note: Fetcharr will not attempt to change volume ownership for your data directories using this method.

2. Remap User (Root Start): Start the container as root (--user 0:0) and provide PUID and PGID environment variables. Fetcharr will start as root to modify volume mount ownership and then drop privileges. This is more flexible but considered less secure.

Unraid Users: Unraid typically uses 99:100 (nobody:users). Use one of the methods above, adding the flag to the 'Extra Parameters' field in the container template (ensure 'Advanced View' is enabled).

# Method 1: Runtime User Setting (Docker)
docker run --user 99:100 ... egg82/fetcharr:latest

# Method 2: Remap User (Docker)
docker run --user 0:0 -e PUID=99 -e PGID=100 ... egg82/fetcharr:latest

The following manifest sets up a Fetcharr deployment in Kubernetes, including PersistentVolumeClaims (PVCs) for config (1Gi), cache (5Gi), logs (10Gi), and plugins (5Gi). It also includes a security context for running as a non-root user (UID 1000).

apiVersion: v1
kind: Namespace
metadata:
  name: fetcharr
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: config
  namespace: fetcharr
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 1Gi
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: cache
  namespace: fetcharr
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: logs
  namespace: fetcharr
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 10Gi
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: plugins
  namespace: fetcharr
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app.kubernetes.io/name: fetcharr
  name: fetcharr
  namespace: fetcharr
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: fetcharr
  template:
    metadata:
      labels:
        app.kubernetes.io/name: fetcharr
    spec:
      securityContext:
        fsGroup: 1000
        fsGroupChangePolicy: OnRootMismatch
        seccompProfile:
          type: RuntimeDefault
      containers:
        - image: egg82/fetcharr:<use-real-version>
          name: fetcharr
          securityContext:
            runAsUser: 1000
            runAsGroup: 1000
            allowPrivilegeEscalation: false
            runAsNonRoot: true
            capabilities:
              drop: ["ALL"]
          resources:
            requests:
              cpu: 50m
              memory: 150Mi
            limits:
              cpu: 500m
              memory: 1Gi
          env:
            - name: VERIFY_CERTS
              value: "true"
            - name: SSL_PATH
              value: /etc/ssl/certs/ca-bundle.crt
            - name: SEARCH_AMOUNT
              value: "5"
            - name: SEARCH_INTERVAL
              value: 1hour
            - name: RADARR_0_URL
              value: https://radarr.home.lab
            - name: RADARR_0_API_KEY
              value: e8ea891d72ff973fa6db0d34369a60a7
            - name: SONARR_0_URL
              value: https://sonarr.home.lab
            - name: SONARR_0_API_KEY
              value: 71730b5dfaa4293fe0c050844c10df66
            - name: SONARR_1_URL
              value: https://anime.home.lab
            - name: SONARR_1_API_KEY
              value: bdb84dc8e4b787c76be8aae2dfe9bd19
          volumeMounts:
            - mountPath: /app/config
              name: config
            - mountPath: /app/cache
              name: cache
            - mountPath: /app/logs
              name: logs
            - mountPath: /app/plugins
              name: plugins
      volumes:
        - name: config
          persistentVolumeClaim:
            claimName: config
        - name: cache
          persistentVolumeClaim:
            claimName: cache
        - name: logs
          persistentVolumeClaim:
            claimName: logs
        - name: plugins
          persistentVolumeClaim:
            claimName: plugins

Plugins are .jar files loaded from the directory specified by PLUGIN_DIR. They are loaded in natural sort order (e.g., 00-plugin.jar loads before 10-plugin.jar).

Manual Installation

Drop .jar files into the plugin directory and restart Fetcharr.

Automatic Installation via plugins.yaml

You can automate plugin downloads by creating a plugins.yaml file in your configuration directory. This file supports direct downloads and manifest references.

Direct Download Options:

• url: The download URL.
• filename: The name to save the file as in the plugin directory.
• sha256: (Recommended) The SHA256 checksum for verification.

Manifest Reference:

• manifest: A URL to another YAML-formatted plugin list. Manifests can be recursive, but Fetcharr detects and ignores loops.

plugins:
  - url: https://some.web.domain/some/path/some-plugin-1.0.0.jar
    filename: 01-some-plugin.jar

  - url: https://another.web.domain/another/path/v1.2.3/another-plugin.jar
    filename: 02-another-plugin.jar
    sha256: 396d448073cf44195508216fca8668cfd6ab395bb447a077227b17d521dec80b

  - manifest: https://some.web.domain/whatever/path/manifest.yaml