Aniworld/docs/CONFIGURATION.md

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.

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

Source: src/config/settings.py

---

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

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

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

---

3. Configuration File (config.json)

Location: data/config.json

File Structure

{
    "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

---

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

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

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

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

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

Logging Level Validation

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

Source: src/server/models/config.py

Backup Path Validation

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

Source: src/server/models/config.py

---

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

# 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

# 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

---

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 - Configuration API endpoints
• DEVELOPMENT.md - Development environment setup
• ARCHITECTURE.md - Configuration service architecture