### Environment Variables Setup

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/development.md

Copy the example environment file and edit it with your development credentials.

```bash
cp .env.example .env
```

```env
MONGODB_URI=your_mongodb_uri
FANART_API=your_fanart_key
TMDB_API_KEY=your_tmdb_key
RPDB_API_KEY=your_rpdb_key
HOST_NAME=http://localhost:3232
PORT=3232
```

--------------------------------

### Copy Example .env File

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/ENVIRONMENT_VARIABLES.md

Copy the example .env file to start configuring your environment variables.

```bash
cp .env.example .env
# Edit .env with your settings
```

--------------------------------

### Development Server Start

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/api.md

Command to start the development server for the addon.

```bash
npm run dev:server
```

--------------------------------

### Start TMDB Addon Server Manually

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/self-hosting.md

Starts the TMDB addon server using Node.js after manual installation and build.

```bash
node addon/server.js
```

--------------------------------

### Install Dependencies

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/development.md

Install all project dependencies using npm.

```bash
npm install
```

--------------------------------

### Start Development Servers

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/development.md

Start the backend and frontend development servers in separate terminals.

```bash
# Terminal 1 - Backend
npm run dev:server

# Terminal 2 - Frontend
npm run dev
```

--------------------------------

### Manifest Response Example

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/api.md

Example structure of the manifest response.

```json
{
  "id": "tmdb-addon",
  "version": "1.0.0",
  "name": "TMDB Addon",
  "description": "TMDB Addon for Stremio",
  "resources": ["catalog", "meta", "stream"],
  "types": ["movie", "series"],
  "catalogs": [...] 
}
```

--------------------------------

### Get Movie Details Example

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/api.md

Example HTTP request to retrieve details for a specific movie.

```http
GET /meta/movie/tmdb:106646.json
```

--------------------------------

### Catalog Response Example

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/api.md

Example structure of the catalog response, listing metas.

```json
{
  "metas": [
    {
      "id": "tmdb:106646",
      "type": "movie",
      "name": "Movie Title",
      "poster": "https://image.url/poster.jpg",
      "background": "https://image.url/background.jpg"
    }
  ]
}
```

--------------------------------

### Minimal Setup (.env)

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/ENVIRONMENT_VARIABLES.md

This snippet shows the minimum required environment variables for setting up the application. It includes essential configurations for database, cache, hostname, and API keys.

```bash
# Required
DATABASE_URL=postgresql://user:pass@localhost:5432/aiometadata
REDIS_URL=redis://localhost:6379
HOST_NAME=my-addon.com
TMDB_API_KEY=your_key_here

# Optional (but recommended)
TVDB_API_KEY=your_key_here

# Recommended
ADMIN_KEY=your_secure_random_key
```

--------------------------------

### Run Development Servers

Source: https://github.com/cedya77/aiometadata/blob/dev/README.md

Commands to start the backend and frontend development servers. Ensure you are in the project directory.

```bash
# Backend
npm run dev:server

# Frontend
npm run dev
```

--------------------------------

### Meta Response Example

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/api.md

Example structure of the meta response, containing detailed item information.

```json
{
  "meta": {
    "id": "tmdb:106646",
    "type": "movie",
    "name": "Movie Title",
    "poster": "https://image.url/poster.jpg",
    "background": "https://image.url/background.jpg",
    "description": "Movie description",
    "runtime": "120",
    "year": 2023,
    "director": ["Director Name"],
    "cast": ["Actor 1", "Actor 2"]
  }
}
```

--------------------------------

### Shared Hosting Setup (.env)

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/ENVIRONMENT_VARIABLES.md

This snippet provides environment variables optimized for shared hosting environments. It uses a SQLite database and configures cache warmup for essential, lightweight operation, with conservative MAL warmup settings.

```bash
# Basic Config
PORT=3232
HOST_NAME=my-addon.com
DATABASE_URL=sqlite:./data/aiometadata.db
REDIS_URL=redis://localhost:6379
TMDB_API_KEY=your_key_here
TVDB_API_KEY=your_key_here  # Optional

# Cache Warmup (essential mode - lightweight)
CACHE_WARMUP_UUID=system-cache-warmer  # Legacy single UUID (still supported)
CACHE_WARMUP_MODE=essential  # Use 'essential' for lightweight warming only

# Conservative MAL Warmup
MAL_WARMUP_ENABLED=true
MAL_WARMUP_INTERVAL_HOURS=12
MAL_WARMUP_QUIET_HOURS_ENABLED=true
MAL_WARMUP_QUIET_HOURS_RANGE=2-8
MAL_WARMUP_PRIORITY_PAGES=1
MAL_WARMUP_DECADES=false
MAL_WARMUP_LOG_LEVEL=silent

# Note: Comprehensive mode not recommended for shared hosting due to resource usage
```

--------------------------------

### Production Setup (.env)

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/ENVIRONMENT_VARIABLES.md

This snippet outlines the environment variables for a production deployment. It includes server settings, database and cache configurations, security, various API keys, and detailed cache warmup settings.

```bash
# Server
PORT=3232
HOST_NAME=my-addon.com
NODE_ENV=production
LOG_LEVEL=info

# Database & Cache
DATABASE_URL=postgresql://user:pass@localhost:5432/aiometadata
REDIS_URL=redis://localhost:6379

# Security
ADMIN_KEY=your_secure_random_key

# API Keys
TMDB_API_KEY=your_key_here
TVDB_API_KEY=your_key_here  # Optional
FANART_API_KEY=your_key_here
MDBLIST_API_KEY=your_key_here
TRAKT_CLIENT_ID=your_key_here  # Optional
TRAKT_CLIENT_SECRET=your_key_here  # Optional
SIMKL_CLIENT_ID=your_key_here  # Optional
SIMKL_CLIENT_SECRET=your_key_here  # Optional

# Cache Warmup Configuration
CACHE_WARMUP_UUIDS=your-user-uuid-here,another-user-uuid  # Multiple UUIDs (up to 3)
CACHE_WARMUP_MODE=comprehensive  # 'essential' or 'comprehensive'

# Comprehensive Catalog Warmup Settings (when mode is 'comprehensive')
CATALOG_WARMUP_INTERVAL_HOURS=24  # Daily
CATALOG_WARMUP_MAX_PAGES_PER_CATALOG=100

# MAL Warmup (optional - can run independently)
MAL_WARMUP_ENABLED=true
MAL_WARMUP_INTERVAL_HOURS=6
MAL_WARMUP_PRIORITY_PAGES=3
MAL_WARMUP_DECADES=true

# Cache
ENABLE_CACHE_WARMING=true

# Cache Cleanup Scheduler
CACHE_CLEANUP_AUTO_ENABLED=true
CACHE_CLEANUP_QUIET_HOURS_ENABLED=false
CACHE_CLEANUP_QUIET_HOURS=02:00-06:00
```

--------------------------------

### Fetch Popular Movies Example

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/api.md

Example HTTP request to fetch a list of popular movies.

```http
GET /catalog/movie/tmdb.top/skip=0&limit=100.json
```

--------------------------------

### Start Docker Compose Services

Source: https://github.com/cedya77/aiometadata/blob/dev/README.md

Command to start the services defined in the Docker Compose file in detached mode.

```bash
docker compose up -d
```

--------------------------------

### MAL Warmup Log Output: Initialization

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/MAL_WARMUP.md

Log output on server start, indicating the MAL catalog warmer has initialized with its configuration.

```log
[MAL Warmer] MAL Catalog Warmer initialized with config: { enabled: true, intervalHours: 6, ... }
[MAL Warmer] Starting background catalog warming...
[MAL Warmer] Warmup scheduled to check every 6 hours
```

--------------------------------

### MAL Warmup Status Response Example

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/MAL_WARMUP.md

Example JSON response from the MAL warmup stats endpoint, showing last run time, items warmed, errors, duration, and configuration details.

```json
{
  "lastRun": "2025-10-17T14:30:00.000Z",
  "itemsWarmed": 16,
  "errors": 0,
  "duration": 28,
  "phase": "complete",
  "nextRun": "2025-10-17T20:30:00.000Z",
  "isWarming": false,
  "config": {
    "enabled": true,
    "intervalHours": 6,
    "quietHoursEnabled": false,
    "quietHoursRange": "2-8",
    "priorityPages": 2,
    "phases": {
      "metadata": true,
      "priority": true,
      "schedule": true,
      "decades": false
    }
  }
}
```

--------------------------------

### Start TMDB Addon with Docker Compose

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/self-hosting.md

Starts the TMDB addon services defined in your docker-compose.yml file in detached mode.

```bash
docker-compose up -d
```

--------------------------------

### Get Configuration Page

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/api.md

Provides access to the configuration page for the addon.

```APIDOC
## GET /configure

### Description
Returns the configuration page for the addon.

### Method
GET

### Endpoint
/configure
```

--------------------------------

### Basic MAL Warmup Configuration

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/MAL_WARMUP.md

Configure essential settings for the MAL warmup service, including enabling/disabling the feature, setting a user UUID for cache warming, defining the interval between warmup runs, and specifying an initial delay after server start.

```bash
# Enable/disable warmup (default: true)
MAL_WARMUP_ENABLED=true

# User UUID to use for cache warming (default: system-cache-warmer)
# Set this to your own UUID to warm caches with your preferred providers/language
CACHE_WARMUP_UUID=system-cache-warmer

# Run warmup every N hours (default: 6)
MAL_WARMUP_INTERVAL_HOURS=6

# Delay before first warmup after server start in seconds (default: 30)
MAL_WARMUP_INITIAL_DELAY_SECONDS=30
```

--------------------------------

### Get Manifest

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/api.md

Retrieves the Stremio addon manifest, which includes addon details and available resources.

```APIDOC
## GET /manifest.json

### Description
Returns the Stremio addon manifest with addon details and available resources.

### Method
GET

### Endpoint
/manifest.json

### Response
#### Success Response (200)
- **id** (string) - Addon identifier
- **version** (string) - Addon version
- **name** (string) - Addon name
- **description** (string) - Addon description
- **resources** (array) - List of available resources (e.g., "catalog", "meta", "stream")
- **types** (array) - Types of content supported (e.g., "movie", "series")
- **catalogs** (array) - Details about available catalogs

#### Response Example
```json
{
  "id": "tmdb-addon",
  "version": "1.0.0",
  "name": "TMDB Addon",
  "description": "TMDB Addon for Stremio",
  "resources": ["catalog", "meta", "stream"],
  "types": ["movie", "series"],
  "catalogs": [...] 
}
```
```

--------------------------------

### Chrome DevTools Backend Debugging

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/development.md

Start the backend server with the inspect flag to enable debugging via Chrome DevTools.

```bash
node --inspect addon/server.js
```

--------------------------------

### MAL Warmup Log Output: Warmup Needed

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/MAL_WARMUP.md

Log output indicating that the warmup interval has elapsed and the MAL catalog warming cycle is starting.

```log
[MAL Warmer] 6h since last MAL warming (threshold: 6h), warming now
[MAL Warmer] 🔥 Starting catalog warmup cycle...
[MAL Warmer] 📚 Phase 1: Warming metadata...
[MAL Warmer] ⭐ Phase 2: Warming high-priority catalogs...
[MAL Warmer] 📅 Phase 3: Warming schedule catalogs...
[MAL Warmer] ✅ Warmup complete: 16 items, 0 errors, 28s. Next run: 2025-10-17T20:30:00.000Z
```

--------------------------------

### Get Catalog

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/api.md

Fetches a catalog of items (movies or series) based on the specified type and ID.

```APIDOC
## GET /catalog/:type/:id/:extra?.json

### Description
Returns a catalog of items based on type and ID.

### Method
GET

### Endpoint
/catalog/:type/:id/:extra?.json

### Parameters
#### Path Parameters
- **type** (string) - Required - Type of content (`movie` or `series`)
- **id** (string) - Required - Catalog ID
- **extra** (string) - Optional - Additional parameters

#### Response
#### Success Response (200)
- **metas** (array) - An array of meta objects, each containing item details.
  - **id** (string) - Unique identifier for the item
  - **type** (string) - Type of the item (`movie` or `series`)
  - **name** (string) - Name of the item
  - **poster** (string) - URL for the item's poster image
  - **background** (string) - URL for the item's background image

#### Response Example
```json
{
  "metas": [
    {
      "id": "tmdb:106646",
      "type": "movie",
      "name": "Movie Title",
      "poster": "https://image.url/poster.jpg",
      "background": "https://image.url/background.jpg"
    }
  ]
}
```
```

--------------------------------

### Build Project

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/development.md

Build the project for production.

```bash
npm run build
```

--------------------------------

### Recommended Configuration for Development

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/MAL_WARMUP.md

Environment variables for configuring the MAL warmer during development, enabling very frequent runs and verbose logging for quick testing and debugging.

```env
MAL_WARMUP_ENABLED=true
MAL_WARMUP_INTERVAL_HOURS=1           # Very frequent for testing
MAL_WARMUP_INITIAL_DELAY_SECONDS=10   # Quick start
MAL_WARMUP_LOG_LEVEL=verbose          # Detailed logs
```

--------------------------------

### Recommended Configuration for VPS / Dedicated Server

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/MAL_WARMUP.md

Environment variables for configuring the MAL warmer on a VPS or dedicated server, allowing for more frequent runs and inclusion of older decades.

```env
MAL_WARMUP_ENABLED=true
MAL_WARMUP_INTERVAL_HOURS=6           # More frequent
MAL_WARMUP_PRIORITY_PAGES=3           # More pages
MAL_WARMUP_DECADES=true               # Include decades (30-day cache)
MAL_WARMUP_LOG_LEVEL=normal
```

--------------------------------

### Clone Repository

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/development.md

Clone the project repository and navigate into the project directory.

```bash
git clone https://github.com/mrcanelas/tmdb-addon.git
cd tmdb-addon
```

--------------------------------

### Recommended Configuration for Shared Hosting

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/MAL_WARMUP.md

Environment variables for configuring the MAL warmer for shared hosting or limited bandwidth environments, prioritizing less frequent runs and lower resource usage.

```env
MAL_WARMUP_ENABLED=true
MAL_WARMUP_INTERVAL_HOURS=12          # Less frequent
MAL_WARMUP_QUIET_HOURS_ENABLED=true
MAL_WARMUP_QUIET_HOURS_RANGE=2-8      # Low-traffic hours
MAL_WARMUP_PRIORITY_PAGES=1           # Fewer pages
MAL_WARMUP_DECADES=false
MAL_WARMUP_LOG_LEVEL=silent
```

--------------------------------

### Get Meta

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/api.md

Retrieves detailed metadata for a specific movie or series item using its type and ID.

```APIDOC
## GET /meta/:type/:id.json

### Description
Returns metadata for a specific item.

### Method
GET

### Endpoint
/meta/:type/:id.json

### Parameters
#### Path Parameters
- **type** (string) - Required - Type of content (`movie` or `series`)
- **id** (string) - Required - TMDB ID or IMDb ID

#### Response
#### Success Response (200)
- **meta** (object) - An object containing detailed metadata for the item.
  - **id** (string) - Unique identifier for the item
  - **type** (string) - Type of the item (`movie` or `series`)
  - **name** (string) - Name of the item
  - **poster** (string) - URL for the item's poster image
  - **background** (string) - URL for the item's background image
  - **description** (string) - Description of the item
  - **runtime** (string) - Runtime of the item in minutes
  - **year** (integer) - Release year of the item
  - **director** (array) - List of directors
  - **cast** (array) - List of cast members

#### Response Example
```json
{
  "meta": {
    "id": "tmdb:106646",
    "type": "movie",
    "name": "Movie Title",
    "poster": "https://image.url/poster.jpg",
    "background": "https://image.url/background.jpg",
    "description": "Movie description",
    "runtime": "120",
    "year": 2023,
    "director": ["Director Name"],
    "cast": ["Actor 1", "Actor 2"]
  }
}
```
```

--------------------------------

### Fast Metadata Indexing

Source: https://github.com/cedya77/aiometadata/blob/dev/README.md

Run these commands to quickly populate genres, producers, and current anime season/schedule data. These are essential for basic catalog functionality.

```bash
docker exec jikan_rest php artisan indexer:genres
docker exec jikan_rest php artisan indexer:producers
docker exec jikan_rest php artisan indexer:anime-current-season
docker exec jikan_rest php artisan indexer:anime-schedule
```

--------------------------------

### MongoDB Initialization Script

Source: https://github.com/cedya77/aiometadata/blob/dev/README.md

A JavaScript script to initialize MongoDB with a user and roles. This script reads credentials from secrets and is mounted into the MongoDB container's entrypoint. This file should be saved as `apps/jikan-rest/mongo-init.js`.

```javascript
const userToCreate = fs.readFileSync('/run/secrets/jikan_db_username', 'utf8');
const userPassword = fs.readFileSync('/run/secrets/jikan_db_password', 'utf8');
db = db.getSiblingDB("admin");
db.createUser({ user: userToCreate, pwd: userPassword, roles: [{ role: "readWrite", db: "jikan" }] });
db = db.getSiblingDB("jikan");
db.createUser({ user: userToCreate, pwd: userPassword, roles: [{ role: "readWrite", db: "jikan" }] });

```

--------------------------------

### Run TMDB Addon with Docker

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/self-hosting.md

Launches the TMDB addon as a Docker container. Ensure you replace placeholder values with your actual MongoDB URI, API keys, and domain.

```bash
docker run -d \
  --name tmdb-addon \
  -p 3232:3232 \
  -e MONGODB_URI=your_mongodb_uri \
  -e FANART_API=your_fanart_key \
  -e TMDB_API_KEY=your_tmdb_key \
  -e RPDB_API_KEY=your_rpdb_key \
  -e HOST_NAME=http://your_domain:3232 \
  mrcanelas/tmdb-addon:latest
```

--------------------------------

### Configuration Endpoint

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/api.md

Access the configuration page for the addon.

```http
GET /configure
```

--------------------------------

### Set Node Environment

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/ENVIRONMENT_VARIABLES.md

Define the Node.js environment mode. Options are 'development' or 'production'. Defaults to 'development'.

```bash
NODE_ENV=production
```

--------------------------------

### Set Host Name

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/ENVIRONMENT_VARIABLES.md

Specify your domain name for generating URLs. Required for production environments.

```bash
HOST_NAME=your-domain.com
```

--------------------------------

### Run Tests and Linting

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/development.md

Execute project tests and linting checks. Specific lint scopes can also be run.

```bash
# Run tests
npm test

# Run all lint scopes
npm run lint

# Or run one scope while iterating
npm run lint:backend
npm run lint:frontend
npm run lint:repo
```

--------------------------------

### Configure PostgreSQL Database URL

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/ENVIRONMENT_VARIABLES.md

Set the connection string for a PostgreSQL database. This is required for database operations.

```bash
DATABASE_URL=postgresql://user:password@localhost:5432/aiometadata
```

--------------------------------

### Generate Secret Files and Set Permissions

Source: https://github.com/cedya77/aiometadata/blob/dev/README.md

Bash commands to create the necessary secret files for database, Redis, and Typesense credentials, and set their permissions to `644`. These files are then used by the Docker services.

```bash
cd apps/jikan-rest && mkdir -p secrets
echo -n "jikan"        > secrets/db_username.txt
echo -n "jikanadmin"   > secrets/db_admin_username.txt
openssl rand -hex 24   > secrets/db_password.txt
openssl rand -hex 24   > secrets/db_admin_password.txt
openssl rand -hex 24   > secrets/redis_password.txt
openssl rand -hex 24   > secrets/typesense_api_key.txt
chmod 644 secrets/*.txt

```

--------------------------------

### MAL Warmup Logging Control

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/MAL_WARMUP.md

Configure the log verbosity level for the MAL warmup service. Options include 'silent', 'normal', and 'verbose'.

```bash
# Log verbosity (default: normal)
# Options: silent, normal, verbose
MAL_WARMUP_LOG_LEVEL=normal
```

--------------------------------

### VS Code Backend Debug Configuration

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/development.md

Launch configuration for debugging the backend server using VS Code.

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Server",
      "program": "${workspaceFolder}/addon/server.js",
      "outFiles": ["${workspaceFolder}/dist/server/**/*.js"]
    }
  ]
}
```

--------------------------------

### Advanced MAL Warmup Configuration

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/MAL_WARMUP.md

Fine-tune advanced settings for the MAL warmup service, such as the delay between individual warmup tasks, the number of pages to warm for priority catalogs, and enabling Safe For Work mode.

```bash
# Extra delay between warmup tasks in ms (default: 100)
MAL_WARMUP_TASK_DELAY_MS=100

# Number of pages to warm for priority catalogs (default: 2)
MAL_WARMUP_PRIORITY_PAGES=2

# Use Safe For Work mode (default: true)
MAL_WARMUP_SFW=true
```

--------------------------------

### Configure SQLite Database URL

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/ENVIRONMENT_VARIABLES.md

Set the connection string for a SQLite database. This is required for database operations.

```bash
DATABASE_URL=sqlite:./data/aiometadata.db
```

--------------------------------

### Manifest Endpoint

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/api.md

Retrieve the Stremio addon manifest, which includes addon details and available resources.

```http
GET /manifest.json
```

--------------------------------

### MAL Warmup Quiet Hours Configuration

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/MAL_WARMUP.md

Configure the quiet hours mode for the MAL warmup service to restrict warming to specific UTC time ranges, which is useful for managing bandwidth on VPS.

```bash
# Enable quiet hours (default: false)
MAL_WARMUP_QUIET_HOURS_ENABLED=true

# Time range in UTC, format: "start-end" (default: 2-8)
MAL_WARMUP_QUIET_HOURS_RANGE=2-8

# Examples:
# "2-8"   = 2:00 AM to 8:00 AM UTC
# "22-6"  = 10:00 PM to 6:00 AM UTC (wrap-around)
# "0-24"  = All day
```

--------------------------------

### Standalone Poster Cache Service with Nginx

Source: https://github.com/cedya77/aiometadata/blob/dev/README.md

Sets up a separate Nginx service for caching poster images. It requires custom Nginx configuration, a stats script, and a purge handler script.

```yaml
  poster-cache:
    image: nginx:alpine
    container_name: poster-cache
    restart: unless-stopped
    volumes:
      - ./poster-cache-nginx.conf:/etc/nginx/nginx.conf:ro
      - ./poster-cache-stats.sh:/stats.sh:ro
      - ./poster-cache-purge-handler.sh:/purge-handler.sh:ro
      - ${DOCKER_DATA_DIR}/poster-cache:/var/cache/nginx
    entrypoint: ["/bin/sh", "-c", "chown -R nginx:nginx /var/cache/nginx && nc -lk -p 9888 -e /purge-handler.sh & /stats.sh & exec nginx -g 'daemon off;'"]
    expose:
      - "8888"
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.poster-cache.rule=Host(`poster-cache.example.com`)"
      - "traefik.http.routers.poster-cache.entrypoints=websecure"
      - "traefik.http.routers.poster-cache.tls.certresolver=letsencrypt"
      - "traefik.http.services.poster-cache.loadbalancer.server.port=8888"
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:8888/health"]
      interval: 30s
      timeout: 10s
      retries: 3
```

--------------------------------

### Make Scripts Executable

Source: https://github.com/cedya77/aiometadata/blob/dev/README.md

This command makes the cache statistics and purge handler scripts executable. Run this after saving the scripts.

```bash
chmod +x poster-cache-stats.sh poster-cache-purge-handler.sh

```

--------------------------------

### Self-Hosting aiometadata with Docker Compose

Source: https://github.com/cedya77/aiometadata/blob/dev/README.md

This Docker Compose configuration sets up aiometadata and its Redis dependency. Ensure a .env file is present for API keys and settings.

```yaml
services:
  aiometadata:
    image: ghcr.io/cedya77/aiometadata:latest
    container_name: aiometadata
    restart: unless-stopped
    ports:
      - "3232:3232"  # Remove this if using Traefik
    # expose:  # Uncomment if using Traefik
    #   - 3232
    env_file:
      - .env
    # labels:  # Optional: Remove if not using Traefik
    #   - "traefik.enable=true"
    #   - "traefik.http.routers.aiometadata.rule=Host(`${AIOMETADATA_HOSTNAME?}`)"
    #   - "traefik.http.routers.aiometadata.entrypoints=websecure"
    #   - "traefik.http.routers.aiometadata.tls.certresolver=letsencrypt"
    #   - "traefik.http.routers.aiometadata.middlewares=authelia@docker"
    #   - "traefik.http.services.aiometadata.loadbalancer.server.port=3232"
    volumes:
      - ${DOCKER_DATA_DIR}/aiometadata/data:/app/addon/data
    depends_on:
      aiometadata_redis:
        condition: service_healthy
    tty: true
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3232/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

  aiometadata_redis:
    image: redis:latest
    container_name: aiometadata_redis
    restart: unless-stopped
    volumes:
      - ${DOCKER_DATA_DIR}/aiometadata/cache:/data
    command: redis-server --appendonly yes --save 3600 1
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  #aiometadata_postgres:
  #  image: postgres:latest
  #  container_name: aiometadata_postgres
  #  restart: unless-stopped
  #  environment:
  #    - POSTGRES_DB=aiometadata
  #    - POSTGRES_USER=postgres
  #    - POSTGRES_PASSWORD=password
  #  volumes:
  #    - ${DOCKER_DATA_DIR}/aiometadata/postgres:/var/lib/postgresql/data
  #  healthcheck:
  #    test: ["CMD-SHELL", "pg_isready -U postgres -d aiometadata"]
  #    interval: 10s
  #    timeout: 5s
  #    retries: 5
```

--------------------------------

### Generate Strong Admin Key

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/ENVIRONMENT_VARIABLES.md

Use openssl to generate a secure, hexadecimal string for your ADMIN_KEY. This is crucial for security.

```bash
openssl rand -hex 32
```

--------------------------------

### Full Anime Catalog Indexing

Source: https://github.com/cedya77/aiometadata/blob/dev/README.md

Initiates a long-running process to index the entire anime catalog. Use the --delay flag to control request rate and avoid rate limiting. Check progress via the log file.

```bash
docker exec -d jikan_rest sh -c 'php artisan indexer:anime --delay=1 >> /tmp/indexer-anime.log 2>&1'
```

--------------------------------

### Jikan REST Environment Configuration

Source: https://github.com/cedya77/aiometadata/blob/dev/README.md

Defines the application's environment variables, including debug mode, log level, application URL, caching settings, database connections, and search engine configuration. This file should be saved as `apps/jikan-rest/.env.compose`.

```env
APP_DEBUG=false
LOG_LEVEL=info
APP_ENV=production
# Indexers self-call the API; must point at RoadRunner's port (8080), NOT the default port 80
APP_URL=http://127.0.0.1:8080
CACHING=true
CACHE_DRIVER=redis
REDIS_HOST=jikan_redis
REDIS_PASSWORD__FILE=/run/secrets/jikan_redis_password
DB_CONNECTION=mongodb
DB_HOST=jikan_mongo
DB_DATABASE=jikan
DB_USERNAME__FILE=/run/secrets/jikan_db_username
DB_ADMIN__FILE=/run/secrets/jikan_db_username
DB_PASSWORD__FILE=/run/secrets/jikan_db_password
SCOUT_DRIVER=typesense
SCOUT_QUEUE=false
TYPESENSE_HOST=jikan_typesense
TYPESENSE_PORT=8108
TYPESENSE_API_KEY__FILE=/run/secrets/jikan_typesense_api_key
CORS_MIDDLEWARE=true
MICROCACHING=true
MICROCACHING_EXPIRE=60

```

--------------------------------

### Configuration to Disable MAL Warmup

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/MAL_WARMUP.md

Environment variable setting to completely disable the MAL catalog warmer.

```env
MAL_WARMUP_ENABLED=false
```

--------------------------------

### Create New Feature Branch

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/development.md

Create a new branch for developing a feature.

```bash
git checkout -b feature/your-feature-name
```

--------------------------------

### Handle TMDB Authentication Success

Source: https://github.com/cedya77/aiometadata/blob/dev/public/tmdb-callback.html

If a `requestToken` is present and the user has approved the connection (or approval is not explicitly denied), this code sends a success message to the parent window via `postMessage` and updates the UI to show a success message. It then closes the window after 2 seconds. If `window.opener` is not available, it displays a message indicating the window can be closed manually.

```javascript
if (requestToken) {
  if (approved !== 'false') {
    if (window.opener) {
      window.opener.postMessage(
        {
          type: 'tmdb_auth_success',
          requestToken: requestToken,
          approved: approved
        },
        window.location.origin
      );
      document.getElementById('container').innerHTML = ` <div class="success">✓</div> <h1>Authentication Successful!</h1> <p>This window will close automatically...</p> `; 
      setTimeout(() => {
        window.close();
      }, 2000);
    } else {
      document.getElementById('container').innerHTML = ` <h1>Authentication Successful!</h1> <p>You can close this window and return to the configuration page.</p> `;
    }
  } else {
    document.getElementById('container').innerHTML = ` <h1>Authorization Denied</h1> <p>You declined the authorization request. You can close this window and try again.</p> `;
    if (window.opener) {
      window.opener.postMessage(
        {
          type: 'tmdb_auth_error',
          error: 'User denied authorization'
        },
        window.location.origin
      );
    }
  }
} else {
  document.getElementById('container').innerHTML = ` <h1>Error</h1> <p>No authentication token received. Please try again.</p> `;
}
```

--------------------------------

### Set Server Port

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/ENVIRONMENT_VARIABLES.md

Configure the port number the server listens on. Defaults to 3232.

```bash
PORT=3000
```

--------------------------------

### Jikan REST Docker Compose Configuration

Source: https://github.com/cedya77/aiometadata/blob/dev/README.md

Defines the services for Jikan REST, MongoDB, Redis, and Typesense, including their images, container configurations, environment variables, secrets, volumes, and health checks. This file should be saved as `apps/jikan-rest/compose.yaml`.

```yaml
secrets:
  jikan_db_username:       { file: ./secrets/db_username.txt }
  jikan_db_password:       { file: ./secrets/db_password.txt }
  jikan_db_admin_username: { file: ./secrets/db_admin_username.txt }
  jikan_db_admin_password: { file: ./secrets/db_admin_password.txt }
  jikan_redis_password:    { file: ./secrets/redis_password.txt }
  jikan_typesense_api_key: { file: ./secrets/typesense_api_key.txt }

services:
  jikan_rest:
    image: docker.io/jikanme/jikan-rest:latest
    container_name: jikan_rest
    hostname: jikan-rest-api
    user: "10001:10001"
    restart: unless-stopped
    env_file: [ .env.compose ]
    secrets: [ jikan_db_username, jikan_db_password, jikan_redis_password, jikan_typesense_api_key ]
    expose: [ 8080 ]
    healthcheck:
      test: ["CMD-SHELL", "wget --spider -q 'http://127.0.0.1:2114/health?plugin=http'"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
    depends_on:
      jikan_mongo:     { condition: service_healthy }
      jikan_redis:     { condition: service_healthy }
      jikan_typesense: { condition: service_started }

  jikan_mongo:
    image: docker.io/mongo:focal
    container_name: jikan_mongo
    hostname: jikan_mongo
    restart: unless-stopped
    command: "--wiredTigerCacheSizeGB 0.5"
    secrets: [ jikan_db_username, jikan_db_password, jikan_db_admin_username, jikan_db_admin_password ]
    environment:
      MONGO_INITDB_ROOT_USERNAME_FILE: /run/secrets/jikan_db_admin_username
      MONGO_INITDB_ROOT_PASSWORD_FILE: /run/secrets/jikan_db_admin_password
      MONGO_INITDB_DATABASE: jikan_admin
    volumes:
      - ${DOCKER_DATA_DIR}/jikan-rest/mongo:/data/db
      - ./mongo-init.js:/docker-entrypoint-initdb.d/mongo-init.js:ro
    healthcheck:
      test: ["CMD-SHELL", "mongosh mongodb://localhost:27017 --quiet --eval 'db.runCommand(\"ping\").ok'"]
      interval: 30s
      timeout: 10s
      retries: 5

  jikan_redis:
    image: docker.io/redis:6-alpine
    container_name: jikan_redis
    hostname: jikan_redis
    restart: unless-stopped
    secrets: [ jikan_redis_password ]
    command: ["/bin/sh", "-c", "redis-server --requirepass \"$$ (cat /run/secrets/jikan_redis_password)\" --appendonly yes"]
    volumes:
      - ${DOCKER_DATA_DIR}/jikan-rest/redis:/data
    healthcheck:
      test: ["CMD-SHELL", "redis-cli -a \"$$ (cat /run/secrets/jikan_redis_password)\" ping | grep -q PONG"]
      interval: 10s
      timeout: 5s
      retries: 5

  jikan_typesense:
    image: docker.io/typesense/typesense:0.24.1
    container_name: jikan_typesense
    hostname: jikan_typesense
    restart: unless-stopped
    entrypoint: /bin/sh
    secrets: [ jikan_typesense_api_key ]
    command: ["-c", "TYPESENSE_API_KEY=\"$$ (cat /run/secrets/jikan_typesense_api_key)\" /opt/typesense-server --data-dir /data"]
    volumes:
      - ${DOCKER_DATA_DIR}/jikan-rest/typesense:/data

```

--------------------------------

### Docker Compose Configuration for TMDB Addon

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/self-hosting.md

Defines the TMDB addon service for Docker Compose. This file specifies the image, port mapping, and environment variables required for running the addon.

```yaml
version: '3' 
services: 
  tmdb-addon: 
    image: mrcanelas/tmdb-addon:latest 
    container_name: tmdb-addon 
    ports: 
      - "3232:3232" 
    environment: 
      - MONGODB_URI=your_mongodb_uri 
      - FANART_API=your_fanart_key 
      - TMDB_API_KEY=your_tmdb_key 
      - RPDB_API_KEY=your_rpdb_key 
      - HOST_NAME=http://your_domain:3232 
    restart: unless-stopped
```

--------------------------------

### Self-Hosted Jikan API Configuration

Source: https://github.com/cedya77/aiometadata/blob/dev/README.md

Configure the Jikan API base URL for anime metadata. This is crucial for ensuring continued functionality after the public Jikan API shutdown. Set this environment variable on the aiometadata service.

```env
JIKAN_API_BASE=http://jikan_rest:8080/v4
```

--------------------------------

### MAL Warmup Log Output: Recently Warmed

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/MAL_WARMUP.md

Log output when the MAL warmer detects that the catalogs were warmed recently and skips the current warmup cycle.

```log
[MAL Warmer] MAL catalogs warmed 145min ago, skipping (next in 215min)
```

--------------------------------

### Using Custom UUID for MAL Warming

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/MAL_WARMUP.md

Specify a custom user UUID to personalize the MAL cache warming process. This allows the warmer to use your preferred metadata providers, language settings, and art provider preferences.

```bash
# Use your own UUID (find it in your addon URL or dashboard)
CACHE_WARMUP_UUID=550e8400-e29b-41d4-a716-446655440000
```

--------------------------------

### Catalog Endpoint

Source: https://github.com/cedya77/aiometadata/blob/dev/docs/api.md

Fetch a catalog of items based on content type and ID. Additional parameters can be provided.

```http
GET /catalog/:type/:id/:extra?.json
```

--------------------------------

### Shell Script for Cache Statistics

Source: https://github.com/cedya77/aiometadata/blob/dev/README.md

This script periodically calculates and writes cache statistics (size, file count) to a JSON file, which is then served by Nginx. It handles cache directory creation and purging. Ensure it's executable.

```sh
#!/bin/sh
# Periodically writes cache stats to a JSON file served by nginx
CACHE_DIR="/var/cache/nginx/posters"
STATS_FILE="/tmp/cache-stats.json"
MAX_SIZE="${POSTER_CACHE_MAX_SIZE:-10g}"
INACTIVE="${POSTER_CACHE_INACTIVE:-30d}"

while true; do
  if [ -d "$CACHE_DIR" ]; then
    size_bytes=$(du -sb "$CACHE_DIR" 2>/dev/null | cut -f1)
    file_count=$(find "$CACHE_DIR" -type f 2>/dev/null | wc -l)
    size_human=$(awk "BEGIN {
      b = ${size_bytes:-0};
      if (b >= 1000000000) printf \"%.1fG\", b/1000000000;
      else if (b >= 1000000) printf \"%.1fM\", b/1000000;
      else if (b >= 1000) printf \"%.1fK\", b/1000;
      else printf \"%dB\", b;
    }")
  else
    size_bytes=0
    size_human="0B"
    file_count=0
  fi

  # Check for purge flag
  if [ -f /tmp/purge-cache ]; then
    rm -f /tmp/purge-cache
    rm -rf "$CACHE_DIR"
    mkdir -p "$CACHE_DIR"
    chown nginx:nginx "$CACHE_DIR"
    size_bytes=0
    size_human="0B"
    file_count=0
  fi

  cat > "$STATS_FILE" <<EOF
{"cached_images":${file_count},"disk_usage":"${size_human}","disk_usage_bytes":${size_bytes},"max_size":"${MAX_SIZE}","inactive":"${INACTIVE}"}
EOF
  sleep 30
done

```