Aniworld/docs/development/setup.md

# AniWorld Installation and Setup Guide

This comprehensive guide will help you install, configure, and deploy the AniWorld anime downloading and management application.

## Table of Contents

1. [Quick Start with Docker](#quick-start-with-docker)
2. [Manual Installation](#manual-installation)
3. [Configuration](#configuration)
4. [Running the Application](#running-the-application)
5. [Monitoring and Health Checks](#monitoring-and-health-checks)
6. [Backup and Maintenance](#backup-and-maintenance)
7. [Troubleshooting](#troubleshooting)
8. [Advanced Deployment](#advanced-deployment)

## Quick Start with Docker

The easiest way to get AniWorld running is using Docker Compose.

### Prerequisites

- Docker Engine 20.10+ 
- Docker Compose 2.0+
- At least 2GB RAM
- 10GB disk space (minimum)

### Installation Steps

1. **Clone the Repository**
   ```bash
   git clone <repository-url>
   cd Aniworld
   ```

2. **Create Environment File**
   ```bash
   cp .env.example .env
   ```

3. **Configure Environment Variables**
   Edit `.env` file:
   ```env
   # Required Settings
   ANIME_DIRECTORY=/path/to/your/anime/collection
   MASTER_PASSWORD=your_secure_password
   
   # Optional Settings  
   WEB_PORT=5000
   HTTP_PORT=80
   HTTPS_PORT=443
   GRAFANA_PASSWORD=grafana_admin_password
   
   # VPN Settings (if using)
   WG_CONFIG_PATH=/path/to/wireguard/config
   ```

4. **Start the Application**
   ```bash
   # Basic deployment
   docker-compose up -d
   
   # With monitoring
   docker-compose --profile monitoring up -d
   
   # With VPN
   docker-compose --profile vpn up -d
   
   # Full deployment with all services
   docker-compose --profile monitoring --profile vpn up -d
   ```

5. **Access the Application**
   - Web Interface: http://localhost:5000
   - Grafana Monitoring: http://localhost:3000 (if monitoring profile enabled)

### Environment File (.env) Template

Create a `.env` file in the root directory:

```env
# Core Application Settings
ANIME_DIRECTORY=/data/anime
MASTER_PASSWORD=change_this_secure_password
DATABASE_PATH=/app/data/aniworld.db
LOG_LEVEL=INFO

# Web Server Configuration
WEB_PORT=5000
WEB_HOST=0.0.0.0
FLASK_ENV=production

# Reverse Proxy Configuration
HTTP_PORT=80
HTTPS_PORT=443

# Monitoring (optional)
GRAFANA_PASSWORD=admin_password

# VPN Configuration (optional)
WG_CONFIG_PATH=/path/to/wg0.conf

# Performance Settings
MAX_DOWNLOAD_WORKERS=4
MAX_SPEED_MBPS=100
CACHE_SIZE_MB=512

# Security Settings
SESSION_TIMEOUT=86400
MAX_LOGIN_ATTEMPTS=5
```

## Manual Installation

### System Requirements

- Python 3.10 or higher
- SQLite 3.35+
- 4GB RAM (recommended)
- 20GB disk space (recommended)

### Installation Steps

1. **Install System Dependencies**

   **Ubuntu/Debian:**
   ```bash
   sudo apt update
   sudo apt install python3 python3-pip python3-venv sqlite3 curl wget
   ```

   **CentOS/RHEL:**
   ```bash
   sudo yum install python3 python3-pip sqlite curl wget
   ```

   **Windows:**
   - Install Python 3.10+ from python.org
   - Install SQLite from sqlite.org
   - Install Git for Windows

2. **Clone and Setup**
   ```bash
   git clone <repository-url>
   cd Aniworld
   
   # Create virtual environment
   python3 -m venv aniworld-env
   
   # Activate virtual environment
   source aniworld-env/bin/activate  # Linux/Mac
   aniworld-env\Scripts\activate     # Windows
   
   # Install Python dependencies
   pip install -r requirements.txt
   ```

3. **Create Configuration**
   ```bash
   cp src/server/config.py.example src/server/config.py
   ```

4. **Configure Application**
   Edit `src/server/config.py`:
   ```python
   import os
   
   class Config:
       # Core settings
       anime_directory = os.getenv('ANIME_DIRECTORY', '/path/to/anime')
       master_password = os.getenv('MASTER_PASSWORD', 'change_me')
       database_path = os.getenv('DATABASE_PATH', './data/aniworld.db')
       
       # Web server settings
       host = os.getenv('WEB_HOST', '127.0.0.1')
       port = int(os.getenv('WEB_PORT', 5000))
       debug = os.getenv('FLASK_DEBUG', 'False').lower() == 'true'
       
       # Performance settings
       max_workers = int(os.getenv('MAX_DOWNLOAD_WORKERS', 4))
       max_speed_mbps = int(os.getenv('MAX_SPEED_MBPS', 100))
   ```

5. **Initialize Database**
   ```bash
   cd src/server
   python -c "from database_manager import init_database_system; init_database_system()"
   ```

6. **Run the Application**
   ```bash
   cd src/server
   python app.py
   ```

## Configuration

### Core Configuration Options

#### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `ANIME_DIRECTORY` | `/app/data` | Path to anime collection |
| `MASTER_PASSWORD` | `admin123` | Web interface password |
| `DATABASE_PATH` | `/app/data/aniworld.db` | SQLite database file path |
| `LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR) |
| `WEB_HOST` | `0.0.0.0` | Web server bind address |
| `WEB_PORT` | `5000` | Web server port |
| `MAX_DOWNLOAD_WORKERS` | `4` | Maximum concurrent downloads |
| `MAX_SPEED_MBPS` | `100` | Download speed limit (Mbps) |

#### Advanced Configuration

Edit `src/server/config.py` for advanced settings:

```python
class Config:
    # Download settings
    download_timeout = 300  # 5 minutes
    retry_attempts = 3
    retry_delay = 5  # seconds
    
    # Cache settings
    cache_size_mb = 512
    cache_ttl = 3600  # 1 hour
    
    # Security settings
    session_timeout = 86400  # 24 hours
    max_login_attempts = 5
    lockout_duration = 300  # 5 minutes
    
    # Monitoring settings
    health_check_interval = 30  # seconds
    metrics_retention_days = 7
```

### Directory Structure Setup

```
/your/anime/directory/
├── Series Name 1/
│   ├── Season 1/
│   ├── Season 2/
│   └── data          # Metadata file
├── Series Name 2/
│   ├── episodes/
│   └── data          # Metadata file
└── ...
```

## Running the Application

### Development Mode

```bash
cd src/server
export FLASK_ENV=development
export FLASK_DEBUG=1
python app.py
```

### Production Mode

#### Using Gunicorn (Recommended)

```bash
# Install gunicorn
pip install gunicorn

# Run with gunicorn
cd src/server
gunicorn -w 4 -b 0.0.0.0:5000 --timeout 300 app:app
```

#### Using systemd Service

Create `/etc/systemd/system/aniworld.service`:

```ini
[Unit]
Description=AniWorld Web Application
After=network.target

[Service]
Type=simple
User=aniworld
WorkingDirectory=/opt/aniworld/src/server
Environment=PATH=/opt/aniworld/aniworld-env/bin
Environment=ANIME_DIRECTORY=/data/anime
Environment=MASTER_PASSWORD=your_password
ExecStart=/opt/aniworld/aniworld-env/bin/gunicorn -w 4 -b 0.0.0.0:5000 app:app
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

Enable and start:
```bash
sudo systemctl daemon-reload
sudo systemctl enable aniworld
sudo systemctl start aniworld
```

### Using Docker

#### Single Container
```bash
docker run -d \
  --name aniworld \
  -p 5000:5000 \
  -v /path/to/anime:/app/data/anime \
  -v /path/to/data:/app/data \
  -e MASTER_PASSWORD=your_password \
  aniworld:latest
```

#### Docker Compose (Recommended)
```bash
docker-compose up -d
```

## Monitoring and Health Checks

### Health Check Endpoints

| Endpoint | Purpose |
|----------|---------|
| `/health` | Basic health check for load balancers |
| `/api/health/system` | System resource metrics |
| `/api/health/database` | Database connectivity |
| `/api/health/dependencies` | External dependencies |
| `/api/health/detailed` | Comprehensive health report |
| `/api/health/ready` | Kubernetes readiness probe |
| `/api/health/live` | Kubernetes liveness probe |
| `/api/health/metrics` | Prometheus metrics |

### Monitoring with Grafana

1. **Enable Monitoring Profile**
   ```bash
   docker-compose --profile monitoring up -d
   ```

2. **Access Grafana**
   - URL: http://localhost:3000
   - Username: admin
   - Password: (set in GRAFANA_PASSWORD env var)

3. **Import Dashboards**
   - System metrics dashboard
   - Application performance dashboard
   - Download statistics dashboard

### Log Management

**Viewing Logs:**
```bash
# Docker logs
docker-compose logs -f aniworld-web

# System logs (if using systemd)
journalctl -u aniworld -f

# Application logs
tail -f src/server/logs/app.log
```

**Log Rotation Configuration:**
Create `/etc/logrotate.d/aniworld`:
```
/opt/aniworld/src/server/logs/*.log {
    daily
    rotate 30
    compress
    delaycompress
    missingok
    notifempty
    create 644 aniworld aniworld
    postrotate
        systemctl reload aniworld
    endscript
}
```

## Backup and Maintenance

### Database Backup

**Manual Backup:**
```bash
# Via API
curl -X POST "http://localhost:5000/api/database/backups/create" \
  -H "Content-Type: application/json" \
  -d '{"backup_type": "full", "description": "Manual backup"}'

# Direct SQLite backup
sqlite3 /app/data/aniworld.db ".backup /path/to/backup.db"
```

**Automated Backup Script:**
```bash
#!/bin/bash
# backup.sh
BACKUP_DIR="/backups"
DATE=$(date +%Y%m%d_%H%M%S)
DB_PATH="/app/data/aniworld.db"

# Create backup
sqlite3 "$DB_PATH" ".backup $BACKUP_DIR/aniworld_$DATE.db"

# Compress
gzip "$BACKUP_DIR/aniworld_$DATE.db"

# Clean old backups (keep 30 days)
find "$BACKUP_DIR" -name "aniworld_*.db.gz" -mtime +30 -delete
```

**Cron Job for Daily Backups:**
```bash
# Add to crontab
0 2 * * * /opt/aniworld/scripts/backup.sh
```

### Database Maintenance

**Vacuum Database (reclaim space):**
```bash
curl -X POST "http://localhost:5000/api/database/maintenance/vacuum"
```

**Update Statistics:**
```bash
curl -X POST "http://localhost:5000/api/database/maintenance/analyze"
```

**Integrity Check:**
```bash
curl -X POST "http://localhost:5000/api/database/maintenance/integrity-check"
```

## Troubleshooting

### Common Issues

#### 1. Permission Denied Errors
```bash
# Fix file permissions
chown -R aniworld:aniworld /opt/aniworld
chmod -R 755 /opt/aniworld

# Fix data directory permissions
chown -R aniworld:aniworld /data/anime
```

#### 2. Database Lock Errors
```bash
# Check for hung processes
ps aux | grep aniworld

# Kill hung processes
pkill -f aniworld

# Restart service
systemctl restart aniworld
```

#### 3. High Memory Usage
```bash
# Check memory usage
curl "http://localhost:5000/api/health/performance"

# Restart application to free memory
docker-compose restart aniworld-web
```

#### 4. Network Connectivity Issues
```bash
# Test network connectivity
curl "http://localhost:5000/api/health/dependencies"

# Check DNS resolution
nslookup aniworld.to

# Test with VPN if configured
docker-compose exec aniworld-web curl ifconfig.io
```

### Performance Tuning

#### 1. Increase Worker Processes
```env
MAX_DOWNLOAD_WORKERS=8
```

#### 2. Adjust Speed Limits
```env
MAX_SPEED_MBPS=200
```

#### 3. Increase Cache Size
```env
CACHE_SIZE_MB=1024
```

#### 4. Database Optimization
```bash
# Regular maintenance
sqlite3 /app/data/aniworld.db "VACUUM; ANALYZE;"

# Enable WAL mode for better concurrency
sqlite3 /app/data/aniworld.db "PRAGMA journal_mode=WAL;"
```

### Debug Mode

Enable debug logging:
```env
LOG_LEVEL=DEBUG
FLASK_DEBUG=1
```

View debug information:
```bash
# Check application logs
docker-compose logs -f aniworld-web

# Check system health
curl "http://localhost:5000/api/health/detailed"
```

## Advanced Deployment

### Load Balancing with Multiple Instances

#### Docker Swarm
```yaml
version: '3.8'
services:
  aniworld-web:
    image: aniworld:latest
    deploy:
      replicas: 3
      update_config:
        parallelism: 1
        delay: 30s
    networks:
      - aniworld
```

#### Kubernetes Deployment
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: aniworld-web
spec:
  replicas: 3
  selector:
    matchLabels:
      app: aniworld-web
  template:
    metadata:
      labels:
        app: aniworld-web
    spec:
      containers:
      - name: aniworld-web
        image: aniworld:latest
        ports:
        - containerPort: 5000
        env:
        - name: ANIME_DIRECTORY
          value: "/data/anime"
        - name: MASTER_PASSWORD
          valueFrom:
            secretKeyRef:
              name: aniworld-secrets
              key: master-password
        volumeMounts:
        - name: anime-data
          mountPath: /data/anime
        - name: app-data
          mountPath: /app/data
        livenessProbe:
          httpGet:
            path: /api/health/live
            port: 5000
          initialDelaySeconds: 30
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /api/health/ready
            port: 5000
          initialDelaySeconds: 5
          periodSeconds: 10
```

### SSL/TLS Configuration

#### Automatic SSL with Let's Encrypt
```bash
# Install certbot
sudo apt install certbot python3-certbot-nginx

# Obtain certificate
sudo certbot --nginx -d your-domain.com

# Auto-renewal
echo "0 12 * * * /usr/bin/certbot renew --quiet" | sudo tee -a /etc/crontab
```

#### Manual SSL Certificate
Place certificates in `docker/nginx/ssl/`:
- `server.crt` - SSL certificate
- `server.key` - Private key

### High Availability Setup

#### Database Replication
```bash
# Master-slave SQLite replication using litestream
docker run -d \
  --name litestream \
  -v /app/data:/data \
  -e LITESTREAM_ACCESS_KEY_ID=your_key \
  -e LITESTREAM_SECRET_ACCESS_KEY=your_secret \
  litestream/litestream \
  replicate /data/aniworld.db s3://your-bucket/db
```

#### Shared Storage
```yaml
# docker-compose.yml with NFS
services:
  aniworld-web:
    volumes:
      - type: volume
        source: anime-data
        target: /app/data/anime
        volume:
          driver: local
          driver_opts:
            type: nfs
            o: addr=your-nfs-server,rw
            device: ":/path/to/anime"
```

### Security Hardening

#### 1. Network Security
```yaml
# Restrict network access
networks:
  aniworld:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16
```

#### 2. Container Security
```dockerfile
# Run as non-root user
USER 1000:1000

# Read-only root filesystem
docker run --read-only --tmpfs /tmp aniworld:latest
```

#### 3. Secrets Management
```bash
# Use Docker secrets
echo "your_password" | docker secret create master_password -

# Use in compose
services:
  aniworld-web:
    secrets:
      - master_password
    environment:
      - MASTER_PASSWORD_FILE=/run/secrets/master_password
```

This installation guide covers all aspects of deploying AniWorld from development to production environments. Choose the deployment method that best fits your infrastructure and requirements.