299 lines
9.6 KiB
Markdown
299 lines
9.6 KiB
Markdown
# 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
|