hi-frontend/docs/guide/installation/docker-run.md

Docker Run Deployment

This guide shows you how to deploy PPanel using the docker run command. This method is suitable for quick testing or simple deployments.

::: tip For production environments, we recommend using Docker Compose instead. :::

Prerequisites

Install Docker

Ubuntu/Debian:

# Update package index
sudo apt-get update

# Install Docker
sudo apt-get install -y ca-certificates curl gnupg lsb-release
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

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

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io

CentOS/RHEL:

# Install Docker
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install -y docker-ce docker-ce-cli containerd.io

# Start Docker
sudo systemctl start docker
sudo systemctl enable docker

Verify Installation

docker --version
sudo docker run hello-world

Quick Start

Step 1: Pull the Image

# Pull latest version
docker pull ppanel/ppanel:latest

# Or pull a specific version
docker pull ppanel/ppanel:v0.1.2

Step 2: Prepare Configuration

# Create configuration directory
mkdir -p ~/ppanel-config

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

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

Step 3: Run Container

Basic Command:

docker run -d \
  --name ppanel \
  -p 8080:8080 \
  -v ~/ppanel-config:/app/etc:ro \
  -v ppanel-data:/app/data \
  --restart unless-stopped \
  ppanel/ppanel:latest

With All Options:

docker run -d \
  --name ppanel \
  -p 8080:8080 \
  -v ~/ppanel-config:/app/etc:ro \
  -v ppanel-data:/app/data \
  -e TZ=UTC \
  --restart unless-stopped \
  --memory="2g" \
  --cpus="2" \
  ppanel/ppanel:latest

Parameter Explanation:

• -d: Run in detached mode (background)
• --name ppanel: Set container name
• -p 8080:8080: Map port (host:container)
• -v ~/ppanel-config:/app/etc:ro: Mount configuration (read-only)
• -v ppanel-data:/app/data: Create data volume
• -e TZ=UTC: Set timezone
• --restart unless-stopped: Auto-restart policy
• --memory="2g": Memory limit
• --cpus="2": CPU limit

Step 4: Verify Running

# Check container status
docker ps | grep ppanel

# View logs
docker logs -f ppanel

# Test access
curl http://localhost:8080

Container Management

View Logs

# View all logs
docker logs ppanel

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

# View last 100 lines
docker logs --tail 100 ppanel

# View logs with timestamps
docker logs -t ppanel

Stop Container

docker stop ppanel

Start Container

docker start ppanel

Restart Container

docker restart ppanel

Remove Container

# Stop and remove
docker stop ppanel
docker rm ppanel

::: warning Removing the container does not delete the data volume. To remove the volume:

docker volume rm ppanel-data

:::

Upgrading

Backup Data

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

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

Upgrade Process

# Pull latest image
docker pull ppanel/ppanel:latest

# Stop old container
docker stop ppanel

# Remove old container
docker rm ppanel

# Start new container with same configuration
docker run -d \
  --name ppanel \
  -p 8080:8080 \
  -v ~/ppanel-config:/app/etc:ro \
  -v ppanel-data:/app/data \
  --restart unless-stopped \
  ppanel/ppanel:latest

# Verify
docker logs -f ppanel

Advanced Usage

Custom Network

# Create network
docker network create ppanel-net

# Run with custom network
docker run -d \
  --name ppanel \
  --network ppanel-net \
  -p 8080:8080 \
  -v ~/ppanel-config:/app/etc:ro \
  -v ppanel-data:/app/data \
  ppanel/ppanel:latest

Environment Variables

docker run -d \
  --name ppanel \
  -p 8080:8080 \
  -e SERVER_PORT=8080 \
  -e DATABASE_TYPE=sqlite \
  -e TZ=Asia/Shanghai \
  -v ~/ppanel-config:/app/etc:ro \
  -v ppanel-data:/app/data \
  ppanel/ppanel:latest

Multiple Instances

# Instance 1 on port 8081
docker run -d \
  --name ppanel-1 \
  -p 8081:8080 \
  -v ~/ppanel-config-1:/app/etc:ro \
  -v ppanel-data-1:/app/data \
  ppanel/ppanel:latest

# Instance 2 on port 8082
docker run -d \
  --name ppanel-2 \
  -p 8082:8080 \
  -v ~/ppanel-config-2:/app/etc:ro \
  -v ppanel-data-2:/app/data \
  ppanel/ppanel:latest

Resource Limits

docker run -d \
  --name ppanel \
  -p 8080:8080 \
  --memory="2g" \
  --memory-swap="2g" \
  --cpus="2" \
  --pids-limit=100 \
  -v ~/ppanel-config:/app/etc:ro \
  -v ppanel-data:/app/data \
  ppanel/ppanel:latest

Troubleshooting

Container Exits Immediately

# Check logs
docker logs ppanel

# Check architecture
uname -m
docker image inspect ppanel/ppanel:latest --format '{{.Architecture}}'

Port Already in Use

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

# Use different port
docker run -d --name ppanel -p 8081:8080 ...

Configuration Not Loading

# Verify mount
docker exec ppanel ls -la /app/etc

# Check file content
docker exec ppanel cat /app/etc/ppanel.yaml

# Check permissions
ls -la ~/ppanel-config/

Access Container Shell

# Access bash (if available)
docker exec -it ppanel bash

# Access sh
docker exec -it ppanel sh

# Run command
docker exec ppanel ls -la /app

Next Steps

• Try Docker Compose for easier management
• Configure Reverse Proxy
• Learn about Configuration

Need Help?

• Check GitHub Issues
• Review Docker logs: docker logs ppanel
• Verify system requirements