Skip to main content

Installation

This guide will help you install TorrentPier on your server.

Requirements​

  • PHP 8.4 or higher
  • MySQL 8.0+ / MariaDB 10.5+ / Percona Server
  • Composer 2.0 or higher
  • Web server: Apache or Nginx

PHP extensions​

Ensure these PHP extensions are installed:

  • BCMath
  • Ctype
  • cURL
  • DOM
  • Fileinfo
  • JSON
  • Mbstring
  • OpenSSL
  • PDO + pdo_mysql
  • Tokenizer
  • XML
  • Zlib

Installation methods​

git clone https://github.com/torrentpier/torrentpier.git
cd torrentpier
composer install
php bull app:install

The installation wizard will guide you through:

  • System requirements check
  • Database configuration
  • Environment setup
  • Running migrations
  • Web server hints

Method 2: Composer create-project​

composer create-project torrentpier/torrentpier
cd torrentpier
php bull app:install

Method 3: Manual installation​

  1. Clone or download the repository
  2. Run composer install
  3. Copy .env.example to .env
  4. Configure database settings in .env
  5. Run migrations: php bull migrate
  6. Configure your web server

Method 4: Docker​

  1. Ensure Docker and Docker Compose are installed on your system

  2. Clone the repository:

    git clone https://github.com/torrentpier/torrentpier.git
    cd torrentpier

  3. Create and configure environment file:

    cp .env.example .env

    IMPORTANT: Update the following values in .env:

    # Application
    TP_HOST=your-domain.com
    APP_CRON_ENABLED=false     # REQUIRED: Set to false for Docker

    # Database (use Docker service names)
    DB_HOST=database
    DB_DATABASE=torrentpier
    DB_USERNAME=torrentpier
    DB_PASSWORD=secret
    DB_ROOT_PASSWORD=rootsecret

    # Cache drivers (use Docker service names)
    REDIS_HOST=redis
    MEMCACHED_HOST=memcached

  4. (Optional) Customize ports if 80/443 are already in use:

    # Add to .env
    TP_PORT=8080
    TP_HTTPS_PORT=8443

  5. Start the application:

    docker compose up -d

  6. Check logs to ensure everything started correctly:

    docker compose logs -f torrentpier

The Docker container will automatically:

  • Wait for database to be ready
  • Create database if it doesn't exist
  • Run migrations
  • Start cron daemon (runs php bull cron:run every 10 minutes)
  • Start FrankenPHP web server
Permissions

We recommend chmod 0755 for folders and chmod 0644 for files.

Bull CLI​

TorrentPier includes a powerful CLI tool for management:

# List all available commands
php bull list

# Run installation wizard
php bull app:install

# Check migration status
php bull migrate:status

# Run pending migrations
php bull migrate

# Clear cache
php bull cache:clear

# View system info
php bull about

Environment configuration​

Edit .env file with your settings:

# Application
APP_ENV=production
TP_HOST=your-domain.com

# Cron manager
APP_CRON_ENABLED=true      # Use TorrentPier cron manager (default)
                           # Set to 'false' for Docker or external crontab

# Database
DB_HOST=localhost          # Use 'database' for Docker
DB_PORT=3306
DB_DATABASE=torrentpier
DB_USERNAME=your_username
DB_PASSWORD=your_password

# Cache drivers (optional)
REDIS_HOST=localhost       # Use 'redis' for Docker
MEMCACHED_HOST=localhost   # Use 'memcached' for Docker
Docker vs Local Installation

For Docker installations:

  • Set DB_HOST=database, REDIS_HOST=redis, MEMCACHED_HOST=memcached (service names)
  • Set APP_CRON_ENABLED=false (Docker container has built-in cron)
  • Add DB_ROOT_PASSWORD for database initialization

For local installations:

  • Use localhost or 127.0.0.1 for all hosts
  • Set APP_CRON_ENABLED=true to use TorrentPier cron manager (default, no external setup)
  • Set APP_CRON_ENABLED=false if using system crontab with php bull cron:run

Web server configuration​

Nginx​

Use the provided configuration template:

cp install/nginx.conf /etc/nginx/sites-available/torrentpier

Or use this basic configuration:

server {
    listen 80;
    server_name your-domain.com;
    root /path/to/torrentpier;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.4-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(ht|git|env) {
        deny all;
    }
}

Apache​

Ensure mod_rewrite is enabled. The .htaccess file is included in the repository.

Caddy​

Use the provided Caddyfile:

cp install/Caddyfile /etc/caddy/Caddyfile

Post-installation​

Set up cron jobs​

TorrentPier supports two cron modes:

Option 1: TorrentPier cron manager (default, recommended for most users)

Set APP_CRON_ENABLED=true in .env. TorrentPier will handle cron internally without external crontab. No additional setup required.

Option 2: External cron (recommended for high-load production)

Set APP_CRON_ENABLED=false in .env and add to your crontab:

# Run maintenance tasks every 10 minutes
*/10 * * * * cd /path/to/torrentpier && php bull cron:run >> /dev/null 2>&1
Docker

Docker installations automatically use external cron (APP_CRON_ENABLED=false). The container runs php bull cron:run every 10 minutes. You must set APP_CRON_ENABLED=false in your .env file when using Docker.

Directory permissions​

The installer sets permissions automatically, but if needed:

chmod -R 755 storage
chown -R www-data:www-data storage

Troubleshooting​

Permission issues​

chmod -R 755 storage
chmod 644 .env

Database connection errors​

  • Verify credentials in .env
  • Check MySQL is running
  • Ensure database exists

Blank page / 500 error​

  • Check PHP error log
  • Verify all PHP extensions are installed
  • Run composer install again

Migration issues​

# Check migration status
php bull migrate:status

# Run migrations with verbose output
php bull migrate -v