lukas.pupkalipinski/Aniworld
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Aniworld/docs/deployment.md
Lukas 9692dfc63b fix test and add doc
2025-10-22 11:30:04 +02:00

15 KiB
Raw Blame History

Aniworld Deployment Guide

Complete deployment guide for the Aniworld Download Manager application.

Table of Contents

  1. System Requirements
  2. Pre-Deployment Checklist
  3. Local Development Setup
  4. Production Deployment
  5. Docker Deployment
  6. Configuration
  7. Database Setup
  8. Security Considerations
  9. Monitoring & Maintenance
  10. 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

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

2. Create Python Environment

Using Conda (Recommended):

conda create -n AniWorld python=3.10
conda activate AniWorld

Using venv:

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

3. Install Dependencies

pip install -r requirements.txt

4. Initialize Database

# 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:

# 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

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

# 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:

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

Install Python:

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

Install System Dependencies:

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

2. Create Application User

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

# Switch to user
sudo su - aniworld

3. Clone and Setup Repository

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

4. Create Virtual Environment

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

5. Install Dependencies

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

6. Configure Production Environment

Create .env file:

# 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

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:

[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

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:

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:

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

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

12. Configure Firewall

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:

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:

docker build -t aniworld:1.0.0 .

2. Docker Compose

Create docker-compose.yml:

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

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:

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

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

PostgreSQL (Production)

Install PostgreSQL:

sudo apt-get install postgresql postgresql-contrib

Create Database:

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:

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

Run Migrations (if applicable):

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:

curl http://localhost:8000/health

Detailed Health:

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

Logging

View Logs:

# 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

# 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

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

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

Troubleshooting

Application Won't Start

Check Logs:

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:

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

SSL/TLS Issues

Certificate Problems:

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

Check Certificate:

openssl s_client -connect yourdomain.com:443

Support

For additional help:

  1. Check User Guide
  2. Review API Reference
  3. Check application logs
  4. File issue on GitHub

Last Updated: October 22, 2025 Version: 1.0.0