Skip to main content
Lionz IPTV Downloader is designed to run efficiently in Docker containers using a multi-service architecture. The application uses FrankenPHP with Laravel Octane for high-performance request handling.

​
Architecture Overview

The Docker deployment consists of three services:
  • Application: Web server running on FrankenPHP with Laravel Octane
  • Queue: Background job processor for download tasks
  • Scheduler: Laravel task scheduler for automated operations
All services share a common SQLite database and communicate with external services (Aria2, Meilisearch) via host networking.

​
Prerequisites

Before deploying, ensure you have:
  • Docker Engine 20.10+
  • Docker Compose v2.0+
  • Aria2 RPC server running on the host
  • Meilisearch server running on the host (port 7700)

​
Quick Start

1

Clone the repository

git clone https://github.com/shekohex/lionz.git
cd lionz
2

Configure environment variables

Copy the example environment file and configure it:
cp .env.example .env
Edit .env and set the required variables:
APP_NAME="Lionz IPTV Downloader"
APP_ENV=production
APP_KEY=  # Generate with: php artisan key:generate
APP_DEBUG=false
APP_URL=http://localhost:8000

# Database (handled by Docker volume)
DB_CONNECTION=sqlite

# Meilisearch configuration
SCOUT_DRIVER=meilisearch
MEILISEARCH_HOST=http://host.docker.internal:7700
MEILISEARCH_KEY=

# Feature flags
TELESCOPE_ENABLED=false
FEATURE_DIRECT_DOWNLOAD_LINKS=true
3

Build and start containers

Build the Docker images and start all services:
docker-compose up -d --build
This will:
  • Build the frontend assets using Bun
  • Create optimized PHP 8.4 containers with all required extensions
  • Start all three services (application, queue, scheduler)
4

Verify deployment

Check that all containers are running:
docker-compose ps
Access the application at http://localhost:8000

​
Service Configuration

​
Application Service

The main web application runs on port 8000: 
application:
  build:
    context: .
    dockerfile: docker/Dockerfile
    target: app
  ports:
    - '8000:80'  # HTTP
  volumes:
    - ./data/database:/data/database
    - caddy_data:/data
    - caddy_config:/config
Key features:
  • Runs FrankenPHP with Laravel Octane for high performance
  • Includes health check endpoint at /up
  • Automatic cache optimization on startup
  • Supports HTTP/2 and compression (zstd, brotli, gzip)

​
Queue Service

Processes background jobs for downloads: 
queue:
  build:
    target: queue
  environment:
    - DB_DATABASE=/data/database/database.sqlite
  volumes:
    - ./data/database:/data/database
Configuration:
  • Memory limit: 2048MB
  • Timeout: Unlimited (long-running downloads)
  • Retry attempts: 3
  • Auto-restart on failure

​
Scheduler Service

Runs periodic tasks: 
scheduler:
  build:
    target: scheduler
  volumes:
    - ./data/database:/data/database
Responsibilities:
  • Media synchronization
  • Cleanup tasks
  • Index maintenance

​
Environment Variables

All services share these environment variables (from docker-compose.yml:11-13):
VariableDefaultDescription
DB_DATABASE/data/database/database.sqliteSQLite database path
ARIA2_RPC_HOSThttp://host.docker.internalAria2 RPC endpoint
MEILISEARCH_HOSThttp://host.docker.internal:7700Meilisearch server
Additional variables from .env file:
VariableDescription
APP_KEYLaravel application encryption key
SYNC_MEDIA_MEMORY_LIMITMemory limit for media sync (default: 512M)
HTTP_CLIENT_USER_AGENTUser agent for HTTP requests
FEATURE_DIRECT_DOWNLOAD_LINKSEnable direct download links

​
Volume Management

The deployment uses persistent volumes: 
volumes:
  caddy_data:    # Caddy data storage
  caddy_config:  # Caddy configuration
Database volume: 
volumes:
  - ./data/database:/data/database
The SQLite database is stored in ./data/database/database.sqlite and shared across all services.

​
HTTPS Configuration

To enable HTTPS, uncomment the HTTPS ports in docker-compose.yml:46-47: 
ports:
  - '8000:80'   # HTTP
  - "443:443"   # HTTPS
  - "443:443/udp"  # HTTP/3
Update your Caddyfile at docker/Caddyfile to configure TLS certificates.

​
Startup Process

When containers start, the entrypoint script (docker/entrypoint.sh:1) performs:
1

Database initialization

Creates SQLite database if it doesn’t exist
2

Run migrations

Applies database schema changes
php artisan migrate --force --graceful
3

Configure application

Runs custom configuration command
php artisan lionz:configure
4

Optimize for production

Caches configuration, routes, views, and events
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan event:cache
5

Link storage

Creates symbolic link for public storage
php artisan storage:link --force
6

Sync search indexes

Updates Meilisearch index settings
php artisan scout:sync-index-settings

​
Managing Containers

​
View logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f application
docker-compose logs -f queue
docker-compose logs -f scheduler

​
Restart services

# All services
docker-compose restart

# Specific service
docker-compose restart application

​
Stop and remove containers

docker-compose down

# Remove volumes as well
docker-compose down -v

​
Update deployment

# Pull latest code
git pull

# Rebuild and restart
docker-compose up -d --build

​
Running Artisan Commands

Execute Laravel Artisan commands inside containers: 
# Inside application container
docker-compose exec application php artisan migrate
docker-compose exec application php artisan cache:clear
docker-compose exec application php artisan queue:restart

# Create a user
docker-compose exec application php artisan tinker

​
Performance Tuning

The Dockerfile (docker/Dockerfile:38-43) includes optimized PHP settings: 
upload_max_filesize = 600M
post_max_size = 0
max_execution_time = 120
max_input_time = 60
memory_limit = 1024M
Installed PHP extensions (docker/Dockerfile:19-35):
  • opcache - Bytecode caching
  • apcu - User cache
  • redis - Session/cache driver
  • memcached - Alternative cache driver
  • imagick - Image processing
  • zstd - Compression

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us