# Configuration Reference

## Document Purpose

This document provides a comprehensive reference for all configuration options in the Aniworld application.

---

## 1. Configuration Overview

### Configuration Sources

Aniworld uses a layered configuration system:

1. **Environment Variables** (highest priority)
2. **`.env` file** in project root
3. **`data/config.json`** file
4. **Default values** (lowest priority)

### Loading Mechanism

Configuration is loaded at application startup via Pydantic Settings.

```python
# src/config/settings.py
class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
```

Source: [src/config/settings.py](../src/config/settings.py#L1-L96)

---

## 2. Environment Variables

### Authentication Settings

| Variable                | Type   | Default          | Description                                                         |
| ----------------------- | ------ | ---------------- | ------------------------------------------------------------------- |
| `JWT_SECRET_KEY`        | string | (random)         | Secret key for JWT token signing. Auto-generated if not set.        |
| `PASSWORD_SALT`         | string | `"default-salt"` | Salt for password hashing.                                          |
| `MASTER_PASSWORD_HASH`  | string | (none)           | Pre-hashed master password. Loaded from config.json if not set.     |
| `MASTER_PASSWORD`       | string | (none)           | **DEVELOPMENT ONLY** - Plaintext password. Never use in production. |
| `SESSION_TIMEOUT_HOURS` | int    | `24`             | JWT token expiry time in hours.                                     |

Source: [src/config/settings.py](../src/config/settings.py#L13-L42)

### Server Settings

| Variable          | Type   | Default                          | Description                                                           |
| ----------------- | ------ | -------------------------------- | --------------------------------------------------------------------- |
| `ANIME_DIRECTORY` | string | `""`                             | Path to anime library directory.                                      |
| `LOG_LEVEL`       | string | `"INFO"`                         | Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL.                 |
| `DATABASE_URL`    | string | `"sqlite:///./data/aniworld.db"` | Database connection string.                                           |
| `CORS_ORIGINS`    | string | `"http://localhost:3000"`        | Comma-separated allowed CORS origins. Use `*` for localhost defaults. |
| `API_RATE_LIMIT`  | int    | `100`                            | Maximum API requests per minute.                                      |

Source: [src/config/settings.py](../src/config/settings.py#L43-L68)

### Provider Settings

| Variable           | Type   | Default         | Description                                   |
| ------------------ | ------ | --------------- | --------------------------------------------- |
| `DEFAULT_PROVIDER` | string | `"aniworld.to"` | Default anime provider.                       |
| `PROVIDER_TIMEOUT` | int    | `30`            | HTTP timeout for provider requests (seconds). |
| `RETRY_ATTEMPTS`   | int    | `3`             | Number of retry attempts for failed requests. |

Source: [src/config/settings.py](../src/config/settings.py#L69-L79)

---

## 3. Configuration File (config.json)

Location: `data/config.json`

### File Structure

```json
{
    "name": "Aniworld",
    "data_dir": "data",
    "scheduler": {
        "enabled": true,
        "interval_minutes": 60
    },
    "logging": {
        "level": "INFO",
        "file": null,
        "max_bytes": null,
        "backup_count": 3
    },
    "backup": {
        "enabled": false,
        "path": "data/backups",
        "keep_days": 30
    },
    "other": {
        "master_password_hash": "$pbkdf2-sha256$...",
        "anime_directory": "/path/to/anime"
    },
    "version": "1.0.0"
}
```

Source: [data/config.json](../data/config.json)

---

## 4. Configuration Sections

### 4.1 General Settings

| Field      | Type   | Default      | Description                    |
| ---------- | ------ | ------------ | ------------------------------ |
| `name`     | string | `"Aniworld"` | Application name.              |
| `data_dir` | string | `"data"`     | Base directory for data files. |

Source: [src/server/models/config.py](../src/server/models/config.py#L62-L66)

### 4.2 Scheduler Settings

Controls automatic library rescanning.

| Field                        | Type | Default | Description                                  |
| ---------------------------- | ---- | ------- | -------------------------------------------- |
| `scheduler.enabled`          | bool | `true`  | Enable/disable automatic scans.              |
| `scheduler.interval_minutes` | int  | `60`    | Minutes between automatic scans. Minimum: 1. |

Source: [src/server/models/config.py](../src/server/models/config.py#L5-L12)

### 4.3 Logging Settings

| Field                  | Type   | Default  | Description                                       |
| ---------------------- | ------ | -------- | ------------------------------------------------- |
| `logging.level`        | string | `"INFO"` | Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL. |
| `logging.file`         | string | `null`   | Optional log file path.                           |
| `logging.max_bytes`    | int    | `null`   | Maximum log file size for rotation.               |
| `logging.backup_count` | int    | `3`      | Number of rotated log files to keep.              |

Source: [src/server/models/config.py](../src/server/models/config.py#L27-L46)

### 4.4 Backup Settings

| Field              | Type   | Default          | Description                      |
| ------------------ | ------ | ---------------- | -------------------------------- |
| `backup.enabled`   | bool   | `false`          | Enable automatic config backups. |
| `backup.path`      | string | `"data/backups"` | Directory for backup files.      |
| `backup.keep_days` | int    | `30`             | Days to retain backups.          |

Source: [src/server/models/config.py](../src/server/models/config.py#L15-L24)

### 4.5 Other Settings (Dynamic)

The `other` field stores arbitrary settings.

| Key                    | Type   | Description                             |
| ---------------------- | ------ | --------------------------------------- |
| `master_password_hash` | string | Hashed master password (pbkdf2-sha256). |
| `anime_directory`      | string | Path to anime library.                  |
| `advanced`             | object | Advanced configuration options.         |

---

## 5. Configuration Precedence

Settings are resolved in this order (first match wins):

1. Environment variable (e.g., `ANIME_DIRECTORY`)
2. `.env` file in project root
3. `data/config.json` (for dynamic settings)
4. Code defaults in `Settings` class

---

## 6. Validation Rules

### Password Requirements

Master password must meet all criteria:

-   Minimum 8 characters
-   At least one uppercase letter
-   At least one lowercase letter
-   At least one digit
-   At least one special character

Source: [src/server/services/auth_service.py](../src/server/services/auth_service.py#L97-L125)

### Logging Level Validation

Must be one of: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`

Source: [src/server/models/config.py](../src/server/models/config.py#L43-L47)

### Backup Path Validation

If `backup.enabled` is `true`, `backup.path` must be set.

Source: [src/server/models/config.py](../src/server/models/config.py#L87-L91)

---

## 7. Example Configurations

### Minimal Development Setup

**.env file:**

```
LOG_LEVEL=DEBUG
ANIME_DIRECTORY=/home/user/anime
```

### Production Setup

**.env file:**

```
JWT_SECRET_KEY=your-secure-random-key-here
DATABASE_URL=postgresql+asyncpg://user:pass@localhost/aniworld
LOG_LEVEL=WARNING
CORS_ORIGINS=https://your-domain.com
API_RATE_LIMIT=60
```

### Docker Setup

```yaml
# docker-compose.yml
environment:
    - JWT_SECRET_KEY=${JWT_SECRET_KEY}
    - DATABASE_URL=sqlite:///./data/aniworld.db
    - ANIME_DIRECTORY=/media/anime
    - LOG_LEVEL=INFO
volumes:
    - ./data:/app/data
    - /media/anime:/media/anime:ro
```

---

## 8. Configuration Backup Management

### Automatic Backups

Backups are created automatically before config changes when `backup.enabled` is `true`.

Location: `data/config_backups/`

Naming: `config_backup_YYYYMMDD_HHMMSS.json`

### Manual Backup via API

```bash
# Create backup
curl -X POST http://localhost:8000/api/config/backups \
  -H "Authorization: Bearer $TOKEN"

# List backups
curl http://localhost:8000/api/config/backups \
  -H "Authorization: Bearer $TOKEN"

# Restore backup
curl -X POST http://localhost:8000/api/config/backups/config_backup_20251213.json/restore \
  -H "Authorization: Bearer $TOKEN"
```

Source: [src/server/api/config.py](../src/server/api/config.py#L67-L142)

---

## 9. Troubleshooting

### Configuration Not Loading

1. Check file permissions on `data/config.json`
2. Verify JSON syntax with a validator
3. Check logs for Pydantic validation errors

### Environment Variable Not Working

1. Ensure variable name matches exactly (case-sensitive)
2. Check `.env` file location (project root)
3. Restart application after changes

### Master Password Issues

1. Password hash is stored in `config.json` under `other.master_password_hash`
2. Delete this field to reset (requires re-setup)
3. Check hash format starts with `$pbkdf2-sha256$`

---

## 10. Related Documentation

-   [API.md](API.md) - Configuration API endpoints
-   [DEVELOPMENT.md](DEVELOPMENT.md) - Development environment setup
-   [ARCHITECTURE.md](ARCHITECTURE.md) - Configuration service architecture