📝 docs: Add documentation
This commit is contained in:
web@ppanel
@@ -0,0 +1,507 @@
|
||||
# Installation
|
||||
|
||||
This guide will help you deploy PPanel on your server using Docker.
|
||||
|
||||
## 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
|
||||
- **Docker**: 20.10+
|
||||
- **Docker Compose**: 2.0+ (optional but recommended)
|
||||
|
||||
### Recommended Requirements
|
||||
- **CPU**: 2+ cores
|
||||
- **Memory**: 2GB+ RAM
|
||||
- **Storage**: 5GB+ available disk space
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Method 1: Using Docker Run
|
||||
|
||||
#### 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
|
||||
|
||||
Create a configuration directory and prepare the configuration file:
|
||||
|
||||
```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 3: Run Container
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name ppanel \
|
||||
-p 8080:8080 \
|
||||
-v $(pwd)/ppanel-config:/app/etc:ro \
|
||||
-v ppanel-data:/app/data \
|
||||
--restart unless-stopped \
|
||||
ppanel/ppanel:latest
|
||||
```
|
||||
|
||||
**Parameter Explanation:**
|
||||
- `-d`: Run container in detached mode (background)
|
||||
- `--name ppanel`: Set container name
|
||||
- `-p 8080:8080`: Map container port 8080 to host port 8080
|
||||
- `-v $(pwd)/ppanel-config:/app/etc:ro`: Mount configuration directory (read-only)
|
||||
- `-v ppanel-data:/app/data`: Create a volume for persistent data storage
|
||||
- `--restart unless-stopped`: Auto-restart container unless manually stopped
|
||||
|
||||
#### Step 4: Verify Running Status
|
||||
|
||||
```bash
|
||||
# Check container status
|
||||
docker ps | grep ppanel
|
||||
|
||||
# View logs
|
||||
docker logs -f ppanel
|
||||
|
||||
# Check if service is accessible
|
||||
curl http://localhost:8080
|
||||
```
|
||||
|
||||
### Method 2: Using Docker Compose (Recommended)
|
||||
|
||||
#### Step 1: Create docker-compose.yml
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
#### Step 2: Prepare Configuration
|
||||
|
||||
```bash
|
||||
# Create configuration directory
|
||||
mkdir -p ppanel-config
|
||||
|
||||
# Copy or create your configuration file
|
||||
# See Configuration Guide for details
|
||||
```
|
||||
|
||||
#### Step 3: Start Services
|
||||
|
||||
```bash
|
||||
# Start in detached mode
|
||||
docker compose up -d
|
||||
|
||||
# View logs
|
||||
docker compose logs -f
|
||||
|
||||
# Check status
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
## 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 (Optional)
|
||||
|
||||
For production deployment, it's recommended to use Nginx or Caddy as a reverse proxy to enable HTTPS.
|
||||
|
||||
**Nginx Example:**
|
||||
|
||||
```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;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Caddy Example:**
|
||||
|
||||
```
|
||||
your-domain.com {
|
||||
reverse_proxy localhost:8080
|
||||
}
|
||||
```
|
||||
|
||||
## Container Management
|
||||
|
||||
### View Logs
|
||||
|
||||
```bash
|
||||
# Docker Run
|
||||
docker logs -f ppanel
|
||||
|
||||
# Docker Compose
|
||||
docker compose logs -f
|
||||
```
|
||||
|
||||
### Stop Container
|
||||
|
||||
```bash
|
||||
# Docker Run
|
||||
docker stop ppanel
|
||||
|
||||
# Docker Compose
|
||||
docker compose stop
|
||||
```
|
||||
|
||||
### Restart Container
|
||||
|
||||
```bash
|
||||
# Docker Run
|
||||
docker restart ppanel
|
||||
|
||||
# Docker Compose
|
||||
docker compose restart
|
||||
```
|
||||
|
||||
### Remove Container
|
||||
|
||||
```bash
|
||||
# Docker Run
|
||||
docker stop ppanel
|
||||
docker rm ppanel
|
||||
|
||||
# Docker Compose
|
||||
docker compose down
|
||||
```
|
||||
|
||||
::: warning Data Persistence
|
||||
Removing containers will not delete volumes. To remove volumes as well, use:
|
||||
```bash
|
||||
docker compose down -v
|
||||
```
|
||||
:::
|
||||
|
||||
## Upgrading
|
||||
|
||||
### Backup Configuration
|
||||
|
||||
Before upgrading, backup your configuration and 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 Steps
|
||||
|
||||
#### Using Docker Run
|
||||
|
||||
```bash
|
||||
# Pull latest image
|
||||
docker pull ppanel/ppanel:latest
|
||||
|
||||
# Stop and remove old container
|
||||
docker stop ppanel
|
||||
docker rm ppanel
|
||||
|
||||
# Start new container with same configuration
|
||||
docker run -d \
|
||||
--name ppanel \
|
||||
-p 8080:8080 \
|
||||
-v $(pwd)/ppanel-config:/app/etc:ro \
|
||||
-v ppanel-data:/app/data \
|
||||
--restart unless-stopped \
|
||||
ppanel/ppanel:latest
|
||||
```
|
||||
|
||||
#### Using Docker Compose
|
||||
|
||||
```bash
|
||||
# Pull latest image
|
||||
docker compose pull
|
||||
|
||||
# Recreate containers with new image
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### Verify Upgrade
|
||||
|
||||
```bash
|
||||
# Check container is running
|
||||
docker ps | grep ppanel
|
||||
|
||||
# Check logs for any errors
|
||||
docker logs ppanel
|
||||
|
||||
# Verify application is accessible
|
||||
curl http://localhost:8080
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Container Exits Immediately
|
||||
|
||||
**Check architecture compatibility:**
|
||||
```bash
|
||||
# Check host architecture
|
||||
uname -m
|
||||
|
||||
# Check image architecture
|
||||
docker image inspect ppanel/ppanel:latest --format '{{.Architecture}}'
|
||||
```
|
||||
|
||||
**Check logs:**
|
||||
```bash
|
||||
docker logs ppanel
|
||||
```
|
||||
|
||||
### Cannot Access Service
|
||||
|
||||
1. **Check if container is running:**
|
||||
```bash
|
||||
docker ps | grep ppanel
|
||||
```
|
||||
|
||||
2. **Check port mapping:**
|
||||
```bash
|
||||
docker port ppanel
|
||||
```
|
||||
|
||||
3. **Check firewall rules:**
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo ufw status
|
||||
sudo ufw allow 8080
|
||||
|
||||
# CentOS/RHEL
|
||||
sudo firewall-cmd --list-ports
|
||||
sudo firewall-cmd --add-port=8080/tcp --permanent
|
||||
sudo firewall-cmd --reload
|
||||
```
|
||||
|
||||
### Configuration Not Taking Effect
|
||||
|
||||
1. **Verify mount path:**
|
||||
```bash
|
||||
docker exec ppanel ls -la /app/etc
|
||||
```
|
||||
|
||||
2. **Check configuration syntax:**
|
||||
```bash
|
||||
docker exec ppanel cat /app/etc/ppanel.yaml
|
||||
```
|
||||
|
||||
3. **Restart container:**
|
||||
```bash
|
||||
docker restart ppanel
|
||||
```
|
||||
|
||||
### Performance Issues
|
||||
|
||||
1. **Check resource usage:**
|
||||
```bash
|
||||
docker stats ppanel
|
||||
```
|
||||
|
||||
2. **Increase container resources** (if using Docker Desktop):
|
||||
- Open Docker Desktop Settings
|
||||
- Go to Resources
|
||||
- Increase CPU and Memory allocation
|
||||
|
||||
3. **Check disk space:**
|
||||
```bash
|
||||
df -h
|
||||
docker system df
|
||||
```
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Using Environment Variables
|
||||
|
||||
You can override configuration via environment variables:
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name ppanel \
|
||||
-p 8080:8080 \
|
||||
-e SERVER_PORT=8080 \
|
||||
-e DATABASE_TYPE=sqlite \
|
||||
-v $(pwd)/ppanel-config:/app/etc:ro \
|
||||
-v ppanel-data:/app/data \
|
||||
--restart unless-stopped \
|
||||
ppanel/ppanel:latest
|
||||
```
|
||||
|
||||
### Running Multiple Instances
|
||||
|
||||
To run multiple instances, use different ports and container names:
|
||||
|
||||
```bash
|
||||
# Instance 1
|
||||
docker run -d \
|
||||
--name ppanel-1 \
|
||||
-p 8081:8080 \
|
||||
-v $(pwd)/ppanel-config-1:/app/etc:ro \
|
||||
-v ppanel-data-1:/app/data \
|
||||
ppanel/ppanel:latest
|
||||
|
||||
# Instance 2
|
||||
docker run -d \
|
||||
--name ppanel-2 \
|
||||
-p 8082:8080 \
|
||||
-v $(pwd)/ppanel-config-2:/app/etc:ro \
|
||||
-v ppanel-data-2:/app/data \
|
||||
ppanel/ppanel:latest
|
||||
```
|
||||
|
||||
### Custom Network
|
||||
|
||||
Create a custom Docker network for better isolation:
|
||||
|
||||
```bash
|
||||
# Create network
|
||||
docker network create ppanel-net
|
||||
|
||||
# Run container on custom network
|
||||
docker run -d \
|
||||
--name ppanel \
|
||||
--network ppanel-net \
|
||||
-p 8080:8080 \
|
||||
-v $(pwd)/ppanel-config:/app/etc:ro \
|
||||
-v ppanel-data:/app/data \
|
||||
ppanel/ppanel:latest
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Configuration Guide](/guide/configuration) - Learn about detailed configuration options
|
||||
- [Admin Dashboard](/admin/dashboard) - Start managing your panel
|
||||
- [API Reference](/api/reference) - Integrate with PPanel API
|
||||
|
||||
## Need Help?
|
||||
|
||||
If you encounter any issues:
|
||||
|
||||
1. Check the [Troubleshooting](#troubleshooting) section above
|
||||
2. Search [GitHub Issues](https://github.com/perfect-panel/ppanel/issues)
|
||||
3. Join our community discussions
|
||||
4. Create a new issue with detailed logs and system information
|
||||
Reference in New Issue
Block a user