hi-frontend/docs/guide/installation/binary.md

Binary Deployment

This guide shows you how to deploy PPanel using pre-built binary executables. This method is suitable for users who prefer not to use Docker or need more control over the deployment.

Prerequisites

• Operating System: Linux (Ubuntu 20.04+, Debian 10+, CentOS 8+)
• Architecture: amd64 (x86_64) or arm64
• Permissions: Root or sudo access
• Dependencies: None (binaries are statically compiled)

Download Binary

Step 1: Check System Architecture

# Check your system architecture
uname -m
# Output: x86_64 (amd64) or aarch64 (arm64)

Step 2: Download Latest Release

Visit the GitHub Releases page or download directly:

::: tip Installation Directory You can install PPanel in any directory. This guide uses /opt/ppanel as an example. If you choose a different directory, adjust the paths in subsequent commands accordingly. :::

# Create installation directory (customizable)
sudo mkdir -p /opt/ppanel
cd /opt/ppanel

# Download for Linux amd64
wget https://github.com/perfect-panel/ppanel/releases/latest/download/gateway-linux-amd64.tar.gz

# Or for Linux arm64
# wget https://github.com/perfect-panel/ppanel/releases/latest/download/gateway-linux-arm64.tar.gz

# Or for macOS amd64
# wget https://github.com/perfect-panel/ppanel/releases/latest/download/gateway-darwin-amd64.tar.gz

# Or for macOS arm64 (Apple Silicon)
# wget https://github.com/perfect-panel/ppanel/releases/latest/download/gateway-darwin-arm64.tar.gz

# Extract
tar -xzf gateway-linux-amd64.tar.gz

# Verify extracted files
ls -la

Expected files:

/opt/ppanel/
├── gateway          # Gateway executable
└── etc/             # Configuration directory
    └── ppanel.yaml  # Configuration file

Configuration

Step 1: Prepare Configuration

# Edit configuration
sudo nano /opt/ppanel/etc/ppanel.yaml

Configuration Example:

::: tip Relative Paths Paths in the configuration (such as Path, logs, etc.) support relative paths. Relative paths are relative to the program's working directory (WorkingDirectory), which is /opt/ppanel in the systemd service. :::

Host: 0.0.0.0
Port: 8080
TLS:
    Enable: false
    CertFile: ""
    KeyFile: ""
Debug: false

Static:
  Admin:
    Enabled: true
    Prefix: /admin
    Path: ./static/admin
  User:
    Enabled: true
    Prefix: /
    Path: ./static/user

JwtAuth:
    AccessSecret: your-secret-key-change-this
    AccessExpire: 604800

Logger:
    ServiceName: ApiService
    Mode: console
    Encoding: plain
    TimeFormat: "2006-01-02 15:04:05.000"
    Path: logs
    Level: info
    MaxContentLength: 0
    Compress: false
    Stat: true
    KeepDays: 0
    StackCooldownMillis: 100
    MaxBackups: 0
    MaxSize: 0
    Rotation: daily
    FileTimeFormat: 2006-01-02T15:04:05.000Z07:00

MySQL:
    Addr: localhost:3306
    Username: your-username
    Password: your-password
    Dbname: ppanel
    Config: charset=utf8mb4&parseTime=true&loc=Asia%2FShanghai
    MaxIdleConns: 10
    MaxOpenConns: 10
    SlowThreshold: 1000

Redis:
    Host: localhost:6379
    Pass: your-redis-password
    DB: 0

::: warning Required Configuration MySQL and Redis are required. Please configure the following before deployment:

• JwtAuth.AccessSecret - Use a strong random secret (required)
• MySQL.* - Configure your MySQL database connection (required)
• Redis.* - Configure your Redis connection (required) :::

Step 2: Create Required Directories

# Create data and log directories
sudo mkdir -p /opt/ppanel/data
sudo mkdir -p /opt/ppanel/logs
sudo mkdir -p /opt/ppanel/static

# Set proper permissions
sudo chmod 755 /opt/ppanel
sudo chmod 700 /opt/ppanel/data
sudo chmod 755 /opt/ppanel/logs
sudo chmod 755 /opt/ppanel/static

Running the Service

Method 1: Direct Execution (Testing)

For quick testing:

# Make binary executable
sudo chmod +x /opt/ppanel/gateway

# Run directly
cd /opt/ppanel
sudo ./gateway

Press Ctrl+C to stop.

Method 2: Systemd Service (Recommended)

Create a systemd service for production deployment:

Step 1: Create Service File

sudo nano /etc/systemd/system/ppanel.service

Service File Content:

[Unit]
Description=PPanel Server
Documentation=https://github.com/perfect-panel/ppanel
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/ppanel
ExecStart=/opt/ppanel/gateway
Restart=always
RestartSec=10

# Security settings
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/ppanel/data /opt/ppanel/logs

# Resource limits
LimitNOFILE=65535
LimitNPROC=4096

# Logging
StandardOutput=journal
StandardError=journal
SyslogIdentifier=ppanel

[Install]
WantedBy=multi-user.target

Step 2: Enable and Start Service

# Reload systemd
sudo systemctl daemon-reload

# Enable service (start on boot)
sudo systemctl enable ppanel

# Start service
sudo systemctl start ppanel

# Check status
sudo systemctl status ppanel

Service Management

Check Status

# Check if service is running
sudo systemctl status ppanel

# View detailed status
sudo systemctl show ppanel

View Logs

# View systemd logs
sudo journalctl -u ppanel -f

# View last 100 lines
sudo journalctl -u ppanel -n 100

# View application logs
sudo tail -f /opt/ppanel/logs/ppanel.log

Start/Stop/Restart

# Start service
sudo systemctl start ppanel

# Stop service
sudo systemctl stop ppanel

# Restart service
sudo systemctl restart ppanel

# Reload configuration (if supported)
sudo systemctl reload ppanel

Enable/Disable Auto-start

# Enable auto-start on boot
sudo systemctl enable ppanel

# Disable auto-start
sudo systemctl disable ppanel

# Check if enabled
sudo systemctl is-enabled ppanel

Post-Installation

Verify Installation

# Check if service is listening
sudo netstat -tlnp | grep 8080

# Or use ss
sudo ss -tlnp | grep 8080

# Test HTTP access
curl http://localhost:8080

# Check process
ps aux | grep ppanel

Access the Application

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

::: warning Default Credentials Default Administrator Account:

• Email: admin@ppanel.dev
• Password: password

Security: Change the default credentials immediately after first login. :::

Configure Firewall

# Ubuntu/Debian (UFW)
sudo ufw allow 8080/tcp
sudo ufw status

# CentOS/RHEL (firewalld)
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload
sudo firewall-cmd --list-ports

Setup Reverse Proxy

For production, use Nginx or Caddy as reverse proxy:

Nginx Configuration (/etc/nginx/sites-available/ppanel):

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

    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;

        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Enable the configuration:

sudo ln -s /etc/nginx/sites-available/ppanel /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Upgrading

Upgrade PPanel directly from the Admin Dashboard. On the dashboard homepage, you can check for new versions and upgrade with one click.

::: tip The system will automatically handle the upgrade process, including downloading the new binary and restarting the service. :::

Troubleshooting

Service Fails to Start

# Check detailed logs
sudo journalctl -u ppanel -xe

# Check configuration syntax
/opt/ppanel/ppanel-server --check-config

# Verify permissions
ls -la /opt/ppanel
sudo chown -R root:root /opt/ppanel

Port Already in Use

# Find what's using the port
sudo lsof -i :8080
sudo netstat -tlnp | grep 8080

# Change port in configuration
sudo nano /opt/ppanel/etc/ppanel.yaml
# Update server.port value

# Restart service
sudo systemctl restart ppanel

Binary Won't Execute

# Check architecture compatibility
uname -m
file /opt/ppanel/gateway

# Check if executable
ls -la /opt/ppanel/gateway
sudo chmod +x /opt/ppanel/gateway

# Check for missing libraries (should be none for static binary)
ldd /opt/ppanel/gateway

High Memory Usage

# Check memory usage
ps aux | grep ppanel
top -p $(pgrep ppanel-server)

# Add memory limit to systemd service
sudo nano /etc/systemd/system/ppanel.service
# Add under [Service]:
# MemoryMax=2G
# MemoryHigh=1.5G

sudo systemctl daemon-reload
sudo systemctl restart ppanel

Database Connection Issues

# Check database file permissions
ls -la /opt/ppanel/data/

# For SQLite, verify path in config
sudo nano /opt/ppanel/etc/ppanel.yaml

# Test database connection
sqlite3 /opt/ppanel/data/ppanel.db "SELECT 1;"

# Check logs for database errors
sudo journalctl -u ppanel | grep -i database

Uninstallation

To completely remove PPanel:

# Stop and disable service
sudo systemctl stop ppanel
sudo systemctl disable ppanel

# Remove service file
sudo rm /etc/systemd/system/ppanel.service
sudo systemctl daemon-reload

# Remove installation directory
sudo rm -rf /opt/ppanel

# Remove firewall rules (if added)
sudo ufw delete allow 8080/tcp
# or
sudo firewall-cmd --permanent --remove-port=8080/tcp
sudo firewall-cmd --reload

Advanced Configuration

Running as Non-Root User

For better security, run as dedicated user:

# Create dedicated user
sudo useradd -r -s /bin/false ppanel

# Change ownership
sudo chown -R ppanel:ppanel /opt/ppanel

# Update systemd service
sudo nano /etc/systemd/system/ppanel.service
# Change: User=ppanel

# If binding to port < 1024, grant capability
sudo setcap 'cap_net_bind_service=+ep' /opt/ppanel/gateway

sudo systemctl daemon-reload
sudo systemctl restart ppanel

Multiple Instances

To run multiple instances:

# Create separate directories
sudo mkdir -p /opt/ppanel-1
sudo mkdir -p /opt/ppanel-2

# Copy binaries and configs
sudo cp -r /opt/ppanel/* /opt/ppanel-1/
sudo cp -r /opt/ppanel/* /opt/ppanel-2/

# Edit configs with different ports
sudo nano /opt/ppanel-1/etc/ppanel.yaml  # port: 8081
sudo nano /opt/ppanel-2/etc/ppanel.yaml  # port: 8082

# Create separate systemd services
sudo cp /etc/systemd/system/ppanel.service /etc/systemd/system/ppanel-1.service
sudo cp /etc/systemd/system/ppanel.service /etc/systemd/system/ppanel-2.service

# Edit service files accordingly
sudo systemctl daemon-reload
sudo systemctl enable ppanel-1 ppanel-2
sudo systemctl start ppanel-1 ppanel-2

Custom Environment Variables

Add environment variables to systemd service:

[Service]
Environment="PPANEL_ENV=production"
Environment="PPANEL_DEBUG=false"
EnvironmentFile=/opt/ppanel/env.conf

Performance Tuning

Optimize File Limits

# Edit limits
sudo nano /etc/security/limits.conf

# Add:
* soft nofile 65535
* hard nofile 65535

# For systemd service, already set in service file:
# LimitNOFILE=65535

Enable Database Optimization

For SQLite:

# Add to ppanel.yaml
database:
  type: sqlite
  path: /opt/ppanel/data/ppanel.db
  options:
    cache_size: -2000
    journal_mode: WAL
    synchronous: NORMAL

Next Steps

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

Need Help?

• Check GitHub Issues
• Review systemd logs: sudo journalctl -u ppanel -f
• Check application logs: tail -f /opt/ppanel/logs/ppanel.log