Docker Compose Deployment

Docker Compose is the recommended deployment method for production environments. It provides better service management, easier configuration, and simplified upgrades.

Prerequisites

Install Docker

If you haven't installed Docker yet, please follow the official installation guide:

Ubuntu/Debian:

bash

# Update package index
sudo apt-get update

# Install required packages
sudo apt-get install -y ca-certificates curl gnupg lsb-release

# Add Docker's official GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Set up the repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

CentOS/RHEL:

bash

# Install yum-utils
sudo yum install -y yum-utils

# Add Docker repository
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# Install Docker Engine
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker

Verify Installation

bash

# Check Docker version
docker --version

# Check Docker Compose version
docker compose version

# Test Docker installation
sudo docker run hello-world

Deployment Steps

Step 1: Create Project Directory

bash

# Create project directory
mkdir -p ~/ppanel
cd ~/ppanel

Step 2: Create docker-compose.yml

Create a docker-compose.yml file with the following content:

yaml

version: '3.8'

services:
  ppanel:
    image: ppanel/ppanel:latest
    container_name: ppanel
    ports:
      - "8080:8080"
    volumes:
      - ./ppanel-config:/app/etc:ro
      - ppanel-data:/app/data
    restart: unless-stopped
    environment:
      - TZ=UTC
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

volumes:
  ppanel-data:
    driver: local

Configuration Explanation:

image: Docker image to use (latest or specific version like v0.1.2)
ports: Map container port 8080 to host port 8080
volumes:
- ./ppanel-config:/app/etc:ro - Configuration directory (read-only)
- ppanel-data:/app/data - Persistent data storage
restart: Auto-restart policy
environment: Set timezone (change to your timezone like Asia/Shanghai)
healthcheck: Monitor service health

Step 3: Prepare Configuration

bash

# Create configuration directory
mkdir -p ppanel-config

# Create configuration file
cat > ppanel-config/ppanel.yaml <<EOF
# PPanel Configuration
server:
  host: 0.0.0.0
  port: 8080

database:
  type: sqlite
  path: /app/data/ppanel.db

# Add more configuration as needed
EOF

TIP

For detailed configuration options, please refer to the Configuration Guide.

Step 4: Start Services

bash

# Pull the latest image
docker compose pull

# Start in detached mode
docker compose up -d

# View logs
docker compose logs -f

Step 5: Verify Deployment

bash

# Check service status
docker compose ps

# Check if service is accessible
curl http://localhost:8080

# View real-time logs
docker compose logs -f ppanel

Post-Installation

Access the Application

After successful installation, you can access:

User Panel: http://your-server-ip:8080
Admin Panel: http://your-server-ip:8080/admin

Default Credentials

Please change the default admin password immediately after first login for security.

Configure Reverse Proxy (Recommended)

For production deployment, it's recommended to use Nginx or Caddy as a reverse proxy to enable HTTPS.

Nginx Configuration:

nginx

server {
    listen 80;
    server_name your-domain.com;

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

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /path/to/your/certificate.crt;
    ssl_certificate_key /path/to/your/private.key;

    location / {
        proxy_pass http://localhost:8080;
        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;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;
    }
}

Caddy Configuration:

your-domain.com {
    reverse_proxy localhost:8080
}

TIP

Caddy automatically handles SSL certificates via Let's Encrypt.

Service Management

View Logs

bash

# View all logs
docker compose logs

# Follow logs in real-time
docker compose logs -f

# View specific service logs
docker compose logs ppanel

Stop Services

bash

# Stop all services
docker compose stop

# Stop specific service
docker compose stop ppanel

Restart Services

bash

# Restart all services
docker compose restart

# Restart specific service
docker compose restart ppanel

Stop and Remove Services

bash

# Stop and remove containers
docker compose down

# Stop and remove containers and volumes
docker compose down -v

Data Persistence

Using docker compose down -v will delete all data volumes. Only use this if you want to completely remove all data.

Upgrading

Backup Before Upgrade

bash

# Backup configuration
tar czf ppanel-config-backup-$(date +%Y%m%d).tar.gz ppanel-config/

# Backup data volume
docker run --rm \
  -v ppanel_ppanel-data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/ppanel-data-backup-$(date +%Y%m%d).tar.gz /data

Upgrade Steps

bash

# Pull latest image
docker compose pull

# Recreate containers with new image
docker compose up -d

# View logs to verify
docker compose logs -f

Rollback

If you encounter issues after upgrading:

bash

# Edit docker-compose.yml and change image to previous version
# image: ppanel/ppanel:v0.1.1

# Restart with previous version
docker compose up -d

Advanced Configuration

Custom Port

To use a different port, edit docker-compose.yml:

yaml

ports:
  - "3000:8080"  # Host port 3000 -> Container port 8080

Multiple Instances

To run multiple instances, create separate directories:

bash

# Instance 1
mkdir ~/ppanel-1
cd ~/ppanel-1
# Create docker-compose.yml with port 8081

# Instance 2
mkdir ~/ppanel-2
cd ~/ppanel-2
# Create docker-compose.yml with port 8082

Resource Limits

Add resource limits to prevent overconsumption:

yaml

services:
  ppanel:
    # ... other config ...
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '0.5'
          memory: 512M

Custom Network

Create a custom network for better isolation:

yaml

version: '3.8'

services:
  ppanel:
    # ... other config ...
    networks:
      - ppanel-net

networks:
  ppanel-net:
    driver: bridge

Troubleshooting

Container Fails to Start

bash

# Check logs for errors
docker compose logs ppanel

# Check container status
docker compose ps

# Verify configuration
docker compose config

Port Already in Use

bash

# Check what's using the port
sudo lsof -i :8080

# Change port in docker-compose.yml
# ports:
#   - "8081:8080"

Permission Issues

bash

# Fix configuration directory permissions
sudo chown -R $USER:$USER ppanel-config/

# Make sure files are readable
chmod 644 ppanel-config/ppanel.yaml

Cannot Access from Outside

Check firewall rules:

bash

# Ubuntu/Debian
sudo ufw allow 8080

# CentOS/RHEL
sudo firewall-cmd --add-port=8080/tcp --permanent
sudo firewall-cmd --reload

Verify service is listening:

bash

docker compose ps
netstat -tlnp | grep 8080

Next Steps

Configuration Guide - Detailed configuration options
Admin Dashboard - Start managing your panel
API Reference - API integration guide

Need Help?

If you encounter any issues:

Check the Troubleshooting section above
Review Docker Compose logs
Search GitHub Issues
Create a new issue with detailed system information and logs

Docker Compose Deployment ​

Prerequisites ​

Install Docker ​

Verify Installation ​

Deployment Steps ​

Step 1: Create Project Directory ​

Step 2: Create docker-compose.yml ​

Step 3: Prepare Configuration ​

Step 4: Start Services ​

Step 5: Verify Deployment ​

Post-Installation ​

Access the Application ​

Configure Reverse Proxy (Recommended) ​

Service Management ​

View Logs ​

Stop Services ​

Restart Services ​

Stop and Remove Services ​

Upgrading ​

Backup Before Upgrade ​

Upgrade Steps ​

Rollback ​

Advanced Configuration ​

Custom Port ​

Multiple Instances ​

Resource Limits ​

Custom Network ​

Troubleshooting ​

Container Fails to Start ​

Port Already in Use ​

Permission Issues ​

Cannot Access from Outside ​

Next Steps ​

Need Help? ​

Docker Compose Deployment

Prerequisites

Install Docker

Verify Installation

Deployment Steps

Step 1: Create Project Directory

Step 2: Create docker-compose.yml

Step 3: Prepare Configuration

Step 4: Start Services

Step 5: Verify Deployment

Post-Installation

Access the Application

Configure Reverse Proxy (Recommended)

Service Management

View Logs

Stop Services

Restart Services

Stop and Remove Services

Upgrading

Backup Before Upgrade

Upgrade Steps

Rollback

Advanced Configuration

Custom Port

Multiple Instances

Resource Limits

Custom Network

Troubleshooting

Container Fails to Start

Port Already in Use

Permission Issues

Cannot Access from Outside

Next Steps

Need Help?