📝 docs: Add documentation
This commit is contained in:
web@ppanel
@@ -0,0 +1,585 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Check your system architecture
|
||||
uname -m
|
||||
# Output: x86_64 (amd64) or aarch64 (arm64)
|
||||
```
|
||||
|
||||
### Step 2: Download Latest Release
|
||||
|
||||
Visit the [GitHub Releases](https://github.com/perfect-panel/ppanel/releases) page or download directly:
|
||||
|
||||
```bash
|
||||
# Create installation directory
|
||||
sudo mkdir -p /opt/ppanel
|
||||
cd /opt/ppanel
|
||||
|
||||
# Download for Linux amd64
|
||||
wget https://github.com/perfect-panel/ppanel/releases/latest/download/ppanel-linux-amd64.tar.gz
|
||||
|
||||
# Or for Linux arm64
|
||||
# wget https://github.com/perfect-panel/ppanel/releases/latest/download/ppanel-linux-arm64.tar.gz
|
||||
|
||||
# Extract
|
||||
tar -xzf ppanel-linux-amd64.tar.gz
|
||||
|
||||
# Verify extracted files
|
||||
ls -la
|
||||
```
|
||||
|
||||
Expected files:
|
||||
```
|
||||
/opt/ppanel/
|
||||
├── ppanel-server # Main server binary
|
||||
├── gateway # Gateway binary
|
||||
└── etc/ # Configuration directory
|
||||
└── ppanel.yaml # Configuration file
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Step 1: Prepare Configuration
|
||||
|
||||
```bash
|
||||
# Copy sample configuration
|
||||
sudo cp etc/ppanel.yaml etc/ppanel.yaml.backup
|
||||
|
||||
# Edit configuration
|
||||
sudo nano etc/ppanel.yaml
|
||||
```
|
||||
|
||||
**Basic Configuration Example:**
|
||||
|
||||
```yaml
|
||||
server:
|
||||
host: 0.0.0.0
|
||||
port: 8080
|
||||
mode: release # debug, release, or test
|
||||
|
||||
database:
|
||||
type: sqlite
|
||||
path: /opt/ppanel/data/ppanel.db
|
||||
# For MySQL/PostgreSQL:
|
||||
# type: mysql
|
||||
# host: localhost
|
||||
# port: 3306
|
||||
# user: ppanel
|
||||
# password: your_password
|
||||
# database: ppanel
|
||||
|
||||
log:
|
||||
level: info # debug, info, warn, error
|
||||
path: /opt/ppanel/logs
|
||||
|
||||
gateway:
|
||||
port: 8080
|
||||
timeout: 30s
|
||||
```
|
||||
|
||||
### Step 2: Create Required Directories
|
||||
|
||||
```bash
|
||||
# Create data and log directories
|
||||
sudo mkdir -p /opt/ppanel/data
|
||||
sudo mkdir -p /opt/ppanel/logs
|
||||
|
||||
# Set proper permissions
|
||||
sudo chmod 755 /opt/ppanel
|
||||
sudo chmod 700 /opt/ppanel/data
|
||||
sudo chmod 755 /opt/ppanel/logs
|
||||
```
|
||||
|
||||
## Running the Service
|
||||
|
||||
### Method 1: Direct Execution (Testing)
|
||||
|
||||
For quick testing:
|
||||
|
||||
```bash
|
||||
# Make binaries executable
|
||||
sudo chmod +x /opt/ppanel/ppanel-server
|
||||
sudo chmod +x /opt/ppanel/gateway
|
||||
|
||||
# Run server directly
|
||||
cd /opt/ppanel
|
||||
sudo ./ppanel-server
|
||||
|
||||
# In another terminal, run gateway (if separate)
|
||||
# sudo ./gateway
|
||||
```
|
||||
|
||||
Press `Ctrl+C` to stop.
|
||||
|
||||
### Method 2: Systemd Service (Recommended)
|
||||
|
||||
Create a systemd service for production deployment:
|
||||
|
||||
#### Step 1: Create Service File
|
||||
|
||||
```bash
|
||||
sudo nano /etc/systemd/system/ppanel.service
|
||||
```
|
||||
|
||||
**Service File Content:**
|
||||
|
||||
```ini
|
||||
[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/ppanel-server
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Check if service is running
|
||||
sudo systemctl status ppanel
|
||||
|
||||
# View detailed status
|
||||
sudo systemctl show ppanel
|
||||
```
|
||||
|
||||
### View Logs
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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`
|
||||
|
||||
### Configure Firewall
|
||||
|
||||
```bash
|
||||
# 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`):
|
||||
|
||||
```nginx
|
||||
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:
|
||||
```bash
|
||||
sudo ln -s /etc/nginx/sites-available/ppanel /etc/nginx/sites-enabled/
|
||||
sudo nginx -t
|
||||
sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
## Upgrading
|
||||
|
||||
### Backup Before Upgrade
|
||||
|
||||
```bash
|
||||
# Stop service
|
||||
sudo systemctl stop ppanel
|
||||
|
||||
# Backup current version
|
||||
sudo cp -r /opt/ppanel /opt/ppanel-backup-$(date +%Y%m%d)
|
||||
|
||||
# Backup database
|
||||
sudo cp /opt/ppanel/data/ppanel.db /opt/ppanel/data/ppanel.db.backup-$(date +%Y%m%d)
|
||||
|
||||
# Backup configuration
|
||||
sudo cp /opt/ppanel/etc/ppanel.yaml /opt/ppanel/etc/ppanel.yaml.backup-$(date +%Y%m%d)
|
||||
```
|
||||
|
||||
### Download and Install New Version
|
||||
|
||||
```bash
|
||||
# Download new version
|
||||
cd /tmp
|
||||
wget https://github.com/perfect-panel/ppanel/releases/latest/download/ppanel-linux-amd64.tar.gz
|
||||
|
||||
# Extract to temporary location
|
||||
mkdir ppanel-new
|
||||
tar -xzf ppanel-linux-amd64.tar.gz -C ppanel-new
|
||||
|
||||
# Backup old binaries
|
||||
sudo mv /opt/ppanel/ppanel-server /opt/ppanel/ppanel-server.old
|
||||
sudo mv /opt/ppanel/gateway /opt/ppanel/gateway.old
|
||||
|
||||
# Install new binaries
|
||||
sudo cp ppanel-new/ppanel-server /opt/ppanel/
|
||||
sudo cp ppanel-new/gateway /opt/ppanel/
|
||||
|
||||
# Set permissions
|
||||
sudo chmod +x /opt/ppanel/ppanel-server
|
||||
sudo chmod +x /opt/ppanel/gateway
|
||||
|
||||
# Start service
|
||||
sudo systemctl start ppanel
|
||||
|
||||
# Check status
|
||||
sudo systemctl status ppanel
|
||||
```
|
||||
|
||||
### Rollback
|
||||
|
||||
If upgrade fails:
|
||||
|
||||
```bash
|
||||
# Stop service
|
||||
sudo systemctl stop ppanel
|
||||
|
||||
# Restore old binaries
|
||||
sudo mv /opt/ppanel/ppanel-server.old /opt/ppanel/ppanel-server
|
||||
sudo mv /opt/ppanel/gateway.old /opt/ppanel/gateway
|
||||
|
||||
# Restore database (if needed)
|
||||
sudo cp /opt/ppanel/data/ppanel.db.backup-YYYYMMDD /opt/ppanel/data/ppanel.db
|
||||
|
||||
# Start service
|
||||
sudo systemctl start ppanel
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Service Fails to Start
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Check architecture compatibility
|
||||
uname -m
|
||||
file /opt/ppanel/ppanel-server
|
||||
|
||||
# Check if executable
|
||||
ls -la /opt/ppanel/ppanel-server
|
||||
sudo chmod +x /opt/ppanel/ppanel-server
|
||||
|
||||
# Check for missing libraries (should be none for static binary)
|
||||
ldd /opt/ppanel/ppanel-server
|
||||
```
|
||||
|
||||
### High Memory Usage
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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/ppanel-server
|
||||
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl restart ppanel
|
||||
```
|
||||
|
||||
### Multiple Instances
|
||||
|
||||
To run multiple instances:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```ini
|
||||
[Service]
|
||||
Environment="PPANEL_ENV=production"
|
||||
Environment="PPANEL_DEBUG=false"
|
||||
EnvironmentFile=/opt/ppanel/env.conf
|
||||
```
|
||||
|
||||
## Performance Tuning
|
||||
|
||||
### Optimize File Limits
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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](/guide/configuration) - Detailed configuration options
|
||||
- [Admin Dashboard](/admin/dashboard) - Start managing your panel
|
||||
- [API Reference](/api/reference) - API integration
|
||||
|
||||
## Need Help?
|
||||
|
||||
- Check [GitHub Issues](https://github.com/perfect-panel/ppanel/issues)
|
||||
- Review systemd logs: `sudo journalctl -u ppanel -f`
|
||||
- Check application logs: `tail -f /opt/ppanel/logs/ppanel.log`
|
||||
@@ -0,0 +1,443 @@
|
||||
# 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](/guide/configuration).
|
||||
:::
|
||||
|
||||
### 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`
|
||||
|
||||
::: warning 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
|
||||
```
|
||||
|
||||
::: warning 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
|
||||
|
||||
1. **Check firewall rules:**
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo ufw allow 8080
|
||||
|
||||
# CentOS/RHEL
|
||||
sudo firewall-cmd --add-port=8080/tcp --permanent
|
||||
sudo firewall-cmd --reload
|
||||
```
|
||||
|
||||
2. **Verify service is listening:**
|
||||
```bash
|
||||
docker compose ps
|
||||
netstat -tlnp | grep 8080
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Configuration Guide](/guide/configuration) - Detailed configuration options
|
||||
- [Admin Dashboard](/admin/dashboard) - Start managing your panel
|
||||
- [API Reference](/api/reference) - API integration guide
|
||||
|
||||
## Need Help?
|
||||
|
||||
If you encounter any issues:
|
||||
|
||||
1. Check the [Troubleshooting](#troubleshooting) section above
|
||||
2. Review [Docker Compose logs](#view-logs)
|
||||
3. Search [GitHub Issues](https://github.com/perfect-panel/ppanel/issues)
|
||||
4. Create a new issue with detailed system information and logs
|
||||
@@ -0,0 +1,348 @@
|
||||
# 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](/guide/installation/docker-compose) instead.
|
||||
:::
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Install Docker
|
||||
|
||||
**Ubuntu/Debian:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
docker --version
|
||||
sudo docker run hello-world
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Step 1: Pull the Image
|
||||
|
||||
```bash
|
||||
# Pull latest version
|
||||
docker pull ppanel/ppanel:latest
|
||||
|
||||
# Or pull a specific version
|
||||
docker pull ppanel/ppanel:v0.1.2
|
||||
```
|
||||
|
||||
### Step 2: Prepare Configuration
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# Check container status
|
||||
docker ps | grep ppanel
|
||||
|
||||
# View logs
|
||||
docker logs -f ppanel
|
||||
|
||||
# Test access
|
||||
curl http://localhost:8080
|
||||
```
|
||||
|
||||
## Container Management
|
||||
|
||||
### View Logs
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
docker stop ppanel
|
||||
```
|
||||
|
||||
### Start Container
|
||||
|
||||
```bash
|
||||
docker start ppanel
|
||||
```
|
||||
|
||||
### Restart Container
|
||||
|
||||
```bash
|
||||
docker restart ppanel
|
||||
```
|
||||
|
||||
### Remove Container
|
||||
|
||||
```bash
|
||||
# Stop and remove
|
||||
docker stop ppanel
|
||||
docker rm ppanel
|
||||
```
|
||||
|
||||
::: warning
|
||||
Removing the container does not delete the data volume. To remove the volume:
|
||||
```bash
|
||||
docker volume rm ppanel-data
|
||||
```
|
||||
:::
|
||||
|
||||
## Upgrading
|
||||
|
||||
### Backup Data
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# Check logs
|
||||
docker logs ppanel
|
||||
|
||||
# Check architecture
|
||||
uname -m
|
||||
docker image inspect ppanel/ppanel:latest --format '{{.Architecture}}'
|
||||
```
|
||||
|
||||
### Port Already in Use
|
||||
|
||||
```bash
|
||||
# Check what's using the port
|
||||
sudo lsof -i :8080
|
||||
|
||||
# Use different port
|
||||
docker run -d --name ppanel -p 8081:8080 ...
|
||||
```
|
||||
|
||||
### Configuration Not Loading
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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](/guide/installation/docker-compose) for easier management
|
||||
- Configure [Reverse Proxy](/guide/installation/docker-compose#configure-reverse-proxy)
|
||||
- Learn about [Configuration](/guide/configuration)
|
||||
|
||||
## Need Help?
|
||||
|
||||
- Check [GitHub Issues](https://github.com/perfect-panel/ppanel/issues)
|
||||
- Review Docker logs: `docker logs ppanel`
|
||||
- Verify system requirements
|
||||
@@ -0,0 +1,57 @@
|
||||
# Installation Overview
|
||||
|
||||
PPanel supports multiple deployment methods to suit different needs and environments. Choose the method that best fits your requirements.
|
||||
|
||||
## Deployment Methods
|
||||
|
||||
### Docker Deployment (Recommended)
|
||||
|
||||
The easiest and most reliable way to deploy PPanel. Docker ensures consistent environments and simplifies updates.
|
||||
|
||||
- **[Docker Run](/guide/installation/docker-run)** - Quick deployment with a single command
|
||||
- **[Docker Compose](/guide/installation/docker-compose)** - Production-ready deployment with better management
|
||||
|
||||
### Traditional Deployment
|
||||
|
||||
- **[Binary Deployment](/guide/installation/binary)** - Deploy using pre-built binaries with systemd service
|
||||
|
||||
### Advanced Deployment
|
||||
|
||||
- **[Kubernetes](/guide/installation/kubernetes)** - Deploy PPanel in Kubernetes clusters for high availability
|
||||
- **[From Source](/guide/installation/from-source)** - Build and run PPanel from source code
|
||||
|
||||
## System Requirements
|
||||
|
||||
### Minimum Requirements
|
||||
- **Operating System**: Linux (Ubuntu 20.04+, Debian 10+, CentOS 8+)
|
||||
- **CPU**: 1 core
|
||||
- **Memory**: 512MB RAM
|
||||
- **Storage**: 1GB available disk space
|
||||
|
||||
### Recommended Requirements
|
||||
- **CPU**: 2+ cores
|
||||
- **Memory**: 2GB+ RAM
|
||||
- **Storage**: 5GB+ available disk space
|
||||
|
||||
## Prerequisites
|
||||
|
||||
All deployment methods require:
|
||||
- Linux-based operating system
|
||||
- Basic command line knowledge
|
||||
- Network access for downloading packages/images
|
||||
|
||||
Specific prerequisites vary by deployment method - check the individual guides for details.
|
||||
|
||||
## Quick Start
|
||||
|
||||
For most users, we recommend starting with Docker Compose:
|
||||
|
||||
1. [Install Docker and Docker Compose](/guide/installation/docker-compose#prerequisites)
|
||||
2. [Download configuration files](/guide/installation/docker-compose#download-configuration)
|
||||
3. [Start the services](/guide/installation/docker-compose#start-services)
|
||||
|
||||
## Need Help?
|
||||
|
||||
- Check our [Troubleshooting Guide](/guide/troubleshooting)
|
||||
- Visit [GitHub Issues](https://github.com/perfect-panel/ppanel/issues)
|
||||
- Join our community discussions
|
||||
Reference in New Issue
Block a user