Aniworld/docs/deployment.md

# Aniworld Deployment Guide

Complete deployment guide for the Aniworld Download Manager application.

## Table of Contents

1. [System Requirements](#system-requirements)
2. [Pre-Deployment Checklist](#pre-deployment-checklist)
3. [Local Development Setup](#local-development-setup)
4. [Production Deployment](#production-deployment)
5. [Docker Deployment](#docker-deployment)
6. [Configuration](#configuration)
7. [Database Setup](#database-setup)
8. [Security Considerations](#security-considerations)
9. [Monitoring & Maintenance](#monitoring--maintenance)
10. [Troubleshooting](#troubleshooting)

## System Requirements

### Minimum Requirements

-   **OS**: Windows 10/11, macOS 10.14+, Ubuntu 20.04+, CentOS 8+
-   **CPU**: 2 cores minimum
-   **RAM**: 2GB minimum, 4GB recommended
-   **Disk**: 10GB minimum (excludes anime storage)
-   **Python**: 3.10 or higher
-   **Browser**: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+

### Recommended Production Setup

-   **OS**: Ubuntu 20.04 LTS or CentOS 8+
-   **CPU**: 4 cores minimum
-   **RAM**: 8GB minimum
-   **Disk**: SSD with 50GB+ free space
-   **Network**: Gigabit connection (for download speed)
-   **Database**: PostgreSQL 12+ (for multi-process deployments)

### Bandwidth Requirements

-   **Download Speed**: 5+ Mbps recommended
-   **Upload**: 1+ Mbps for remote logging
-   **Latency**: <100ms for responsive UI

## Pre-Deployment Checklist

### Before Deployment

-   [ ] System meets minimum requirements
-   [ ] Python 3.10+ installed and verified
-   [ ] Git installed for cloning repository
-   [ ] Sufficient disk space available
-   [ ] Network connectivity verified
-   [ ] Firewall rules configured
-   [ ] Backup strategy planned
-   [ ] SSL/TLS certificates prepared (if using HTTPS)

### Repository

-   [ ] Repository cloned from GitHub
-   [ ] README.md reviewed
-   [ ] LICENSE checked
-   [ ] CONTRIBUTING.md understood
-   [ ] Code review completed

### Configuration

-   [ ] Environment variables prepared
-   [ ] Master password decided
-   [ ] Anime directory paths identified
-   [ ] Download directory paths identified
-   [ ] Backup location planned

### Dependencies

-   [ ] All Python packages available
-   [ ] No version conflicts
-   [ ] Virtual environment ready
-   [ ] Dependencies documented

### Testing

-   [ ] All unit tests passing
-   [ ] Integration tests passing
-   [ ] Load testing completed (production)
-   [ ] Security scanning done

## Local Development Setup

### 1. Clone Repository

```bash
git clone https://github.com/your-repo/aniworld.git
cd aniworld
```

### 2. Create Python Environment

**Using Conda** (Recommended):

```bash
conda create -n AniWorld python=3.10
conda activate AniWorld
```

**Using venv**:

```bash
python3.10 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

### 3. Install Dependencies

```bash
pip install -r requirements.txt
```

### 4. Initialize Database

```bash
# Create data directory
mkdir -p data
mkdir -p logs

# Database is created automatically on first run
```

### 5. Configure Application

Create `.env` file in project root:

```bash
# Core settings
APP_NAME=Aniworld
APP_ENV=development
DEBUG=true
LOG_LEVEL=debug

# Database
DATABASE_URL=sqlite:///./data/aniworld.db

# Server
HOST=127.0.0.1
PORT=8000
RELOAD=true

# Anime settings
ANIME_DIRECTORY=/path/to/anime
DOWNLOAD_DIRECTORY=/path/to/downloads

# Session
JWT_SECRET_KEY=your-secret-key-here
SESSION_TIMEOUT_HOURS=24
```

### 6. Run Application

```bash
python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload
```

### 7. Verify Installation

Open browser: `http://localhost:8000`

Expected:

-   Setup page loads (if first run)
-   No console errors
-   Static files load correctly

### 8. Run Tests

```bash
# All tests
python -m pytest tests/ -v

# Specific test file
python -m pytest tests/unit/test_auth_service.py -v

# With coverage
python -m pytest tests/ --cov=src --cov-report=html
```

## Production Deployment

### 1. System Preparation

**Update System**:

```bash
sudo apt-get update && sudo apt-get upgrade -y
```

**Install Python**:

```bash
sudo apt-get install python3.10 python3.10-venv python3-pip
```

**Install System Dependencies**:

```bash
sudo apt-get install git curl wget build-essential libssl-dev
```

### 2. Create Application User

```bash
# Create non-root user
sudo useradd -m -s /bin/bash aniworld

# Switch to user
sudo su - aniworld
```

### 3. Clone and Setup Repository

```bash
cd /home/aniworld
git clone https://github.com/your-repo/aniworld.git
cd aniworld
```

### 4. Create Virtual Environment

```bash
python3.10 -m venv venv
source venv/bin/activate
```

### 5. Install Dependencies

```bash
pip install --upgrade pip
pip install -r requirements.txt
pip install gunicorn uvicorn
```

### 6. Configure Production Environment

Create `.env` file:

```bash
# Core settings
APP_NAME=Aniworld
APP_ENV=production
DEBUG=false
LOG_LEVEL=info

# Database (use PostgreSQL for production)
DATABASE_URL=postgresql://user:password@localhost:5432/aniworld

# Server
HOST=0.0.0.0
PORT=8000
WORKERS=4

# Anime settings
ANIME_DIRECTORY=/var/aniworld/anime
DOWNLOAD_DIRECTORY=/var/aniworld/downloads
CACHE_DIRECTORY=/var/aniworld/cache

# Session
JWT_SECRET_KEY=$(python -c 'import secrets; print(secrets.token_urlsafe(32))')
SESSION_TIMEOUT_HOURS=24

# Security
ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com
CORS_ORIGINS=https://yourdomain.com

# SSL (if using HTTPS)
SSL_KEYFILE=/path/to/key.pem
SSL_CERTFILE=/path/to/cert.pem
```

### 7. Create Required Directories

```bash
sudo mkdir -p /var/aniworld/{anime,downloads,cache}
sudo chown -R aniworld:aniworld /var/aniworld
sudo chmod -R 755 /var/aniworld
```

### 8. Setup Systemd Service

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

```ini
[Unit]
Description=Aniworld Download Manager
After=network.target

[Service]
Type=notify
User=aniworld
WorkingDirectory=/home/aniworld/aniworld
Environment="PATH=/home/aniworld/aniworld/venv/bin"
ExecStart=/home/aniworld/aniworld/venv/bin/gunicorn \
    -w 4 \
    -k uvicorn.workers.UvicornWorker \
    --bind 0.0.0.0:8000 \
    --timeout 120 \
    --access-logfile - \
    --error-logfile - \
    src.server.fastapi_app:app

Restart=always
RestartSec=10

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

### 9. Enable and Start Service

```bash
sudo systemctl daemon-reload
sudo systemctl enable aniworld
sudo systemctl start aniworld
sudo systemctl status aniworld
```

### 10. Setup Reverse Proxy (Nginx)

Create `/etc/nginx/sites-available/aniworld`:

```nginx
server {
    listen 80;
    server_name yourdomain.com;

    # Redirect to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

    # Security headers
    add_header Strict-Transport-Security "max-age=31536000" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;

    # Proxy settings
    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # WebSocket settings
    location /ws/ {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 86400;
    }
}
```

Enable site:

```bash
sudo ln -s /etc/nginx/sites-available/aniworld /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
```

### 11. Setup SSL with Let's Encrypt

```bash
sudo apt-get install certbot python3-certbot-nginx
sudo certbot certonly --nginx -d yourdomain.com
```

### 12. Configure Firewall

```bash
sudo ufw allow 22/tcp    # SSH
sudo ufw allow 80/tcp    # HTTP
sudo ufw allow 443/tcp   # HTTPS
sudo ufw enable
```

## Docker Deployment

### 1. Build Docker Image

Create `Dockerfile`:

```dockerfile
FROM python:3.10-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# Copy requirements
COPY requirements.txt .

# Install Python dependencies
RUN pip install --no-cache-dir -r requirements.txt

# Copy application
COPY . .

# Expose port
EXPOSE 8000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"

# Run application
CMD ["uvicorn", "src.server.fastapi_app:app", "--host", "0.0.0.0", "--port", "8000"]
```

Build image:

```bash
docker build -t aniworld:1.0.0 .
```

### 2. Docker Compose

Create `docker-compose.yml`:

```yaml
version: "3.8"

services:
    aniworld:
        image: aniworld:1.0.0
        container_name: aniworld
        ports:
            - "8000:8000"
        volumes:
            - ./data:/app/data
            - /path/to/anime:/var/anime
            - /path/to/downloads:/var/downloads
        environment:
            - DATABASE_URL=sqlite:///./data/aniworld.db
            - ANIME_DIRECTORY=/var/anime
            - DOWNLOAD_DIRECTORY=/var/downloads
            - LOG_LEVEL=info
        restart: unless-stopped
        networks:
            - aniworld-net

    nginx:
        image: nginx:alpine
        container_name: aniworld-nginx
        ports:
            - "80:80"
            - "443:443"
        volumes:
            - ./nginx.conf:/etc/nginx/nginx.conf:ro
            - ./ssl:/etc/nginx/ssl:ro
        depends_on:
            - aniworld
        restart: unless-stopped
        networks:
            - aniworld-net

networks:
    aniworld-net:
        driver: bridge
```

### 3. Run with Docker Compose

```bash
docker-compose up -d
docker-compose logs -f
```

## Configuration

### Environment Variables

**Core Settings**:

-   `APP_NAME`: Application name
-   `APP_ENV`: Environment (development, production)
-   `DEBUG`: Enable debug mode
-   `LOG_LEVEL`: Logging level (debug, info, warning, error)

**Database**:

-   `DATABASE_URL`: Database connection string
    -   SQLite: `sqlite:///./data/aniworld.db`
    -   PostgreSQL: `postgresql://user:pass@host:5432/dbname`

**Server**:

-   `HOST`: Server bind address (0.0.0.0 for external access)
-   `PORT`: Server port
-   `WORKERS`: Number of worker processes

**Paths**:

-   `ANIME_DIRECTORY`: Path to anime storage
-   `DOWNLOAD_DIRECTORY`: Path to download storage
-   `CACHE_DIRECTORY`: Temporary cache directory

**Security**:

-   `JWT_SECRET_KEY`: JWT signing key
-   `SESSION_TIMEOUT_HOURS`: Session duration
-   `ALLOWED_HOSTS`: Allowed hostnames
-   `CORS_ORIGINS`: Allowed CORS origins

### Configuration File

Create `config.json` in data directory:

```json
{
    "version": "1.0.0",
    "anime_directory": "/path/to/anime",
    "download_directory": "/path/to/downloads",
    "cache_directory": "/path/to/cache",
    "session_timeout_hours": 24,
    "log_level": "info",
    "max_concurrent_downloads": 3,
    "retry_attempts": 3,
    "retry_delay_seconds": 60
}
```

## Database Setup

### SQLite (Development)

```bash
# Automatically created on first run
# Location: data/aniworld.db
```

### PostgreSQL (Production)

**Install PostgreSQL**:

```bash
sudo apt-get install postgresql postgresql-contrib
```

**Create Database**:

```bash
sudo su - postgres
createdb aniworld
createuser aniworld_user
psql -c "ALTER USER aniworld_user WITH PASSWORD 'password';"
psql -c "GRANT ALL PRIVILEGES ON DATABASE aniworld TO aniworld_user;"
exit
```

**Update Connection String**:

```bash
DATABASE_URL=postgresql://aniworld_user:password@localhost:5432/aniworld
```

**Run Migrations** (if applicable):

```bash
alembic upgrade head
```

## Security Considerations

### Access Control

1. **Master Password**: Use strong, complex password
2. **User Permissions**: Run app with minimal required permissions
3. **Firewall**: Restrict access to necessary ports only
4. **SSL/TLS**: Always use HTTPS in production

### Data Protection

1. **Encryption**: Encrypt JWT secrets and sensitive data
2. **Backups**: Regular automated backups
3. **Audit Logging**: Enable comprehensive logging
4. **Database**: Use PostgreSQL for better security than SQLite

### Network Security

1. **HTTPS**: Use SSL/TLS certificates
2. **CORS**: Configure appropriate CORS origins
3. **Rate Limiting**: Enable rate limiting on all endpoints
4. **WAF**: Consider Web Application Firewall

### Secrets Management

1. **Environment Variables**: Use .env for secrets
2. **Secret Store**: Use tools like HashiCorp Vault
3. **Rotation**: Regularly rotate JWT secrets
4. **Audit**: Monitor access to sensitive data

## Monitoring & Maintenance

### Health Checks

**Basic Health**:

```bash
curl http://localhost:8000/health
```

**Detailed Health**:

```bash
curl http://localhost:8000/health/detailed
```

### Logging

**View Logs**:

```bash
# Systemd
sudo journalctl -u aniworld -f

# Docker
docker logs -f aniworld

# Log file
tail -f logs/app.log
```

### Maintenance Tasks

**Daily**:

-   Check disk space
-   Monitor error logs
-   Verify downloads completing

**Weekly**:

-   Review system performance
-   Check for updates
-   Rotate old logs

**Monthly**:

-   Full system backup
-   Database optimization
-   Security audit

### Updating Application

```bash
# Pull latest code
cd /home/aniworld/aniworld
git pull origin main

# Update dependencies
source venv/bin/activate
pip install --upgrade -r requirements.txt

# Restart service
sudo systemctl restart aniworld
```

### Database Maintenance

```bash
# PostgreSQL cleanup
psql -d aniworld -c "VACUUM ANALYZE;"

# SQLite cleanup
sqlite3 data/aniworld.db "VACUUM;"
```

## Troubleshooting

### Application Won't Start

**Check Logs**:

```bash
sudo journalctl -u aniworld -n 50
```

**Common Issues**:

-   Port already in use: Change port or kill process
-   Database connection: Verify DATABASE_URL
-   File permissions: Check directory ownership

### High Memory Usage

**Solutions**:

-   Reduce worker processes
-   Check for memory leaks in logs
-   Restart application periodically
-   Monitor with `htop` or `top`

### Slow Performance

**Optimization**:

-   Use PostgreSQL instead of SQLite
-   Increase worker processes
-   Add more RAM
-   Optimize database queries
-   Cache static files with CDN

### Downloads Failing

**Check**:

-   Internet connection
-   Anime provider availability
-   Disk space on download directory
-   File permissions

**Debug**:

```bash
curl -v http://provider-url/stream
```

### SSL/TLS Issues

**Certificate Problems**:

```bash
sudo certbot renew --dry-run
sudo systemctl restart nginx
```

**Check Certificate**:

```bash
openssl s_client -connect yourdomain.com:443
```

---

## Support

For additional help:

1. Check [User Guide](./user_guide.md)
2. Review [API Reference](./api_reference.md)
3. Check application logs
4. File issue on GitHub

---

**Last Updated**: October 22, 2025
**Version**: 1.0.0