3x-ui/README.Docker.md

🐳 3X-UI Docker Setup with PostgreSQL Support

This guide explains how to run 3X-UI with Docker, supporting both SQLite (default) and PostgreSQL databases.

📋 Quick Start

Option 1: SQLite (Default, Recommended for most users)

# Clone the repository
git clone https://github.com/MHSanaei/3x-ui.git
cd 3x-ui

# Start with SQLite (default)
docker-compose up -d

Option 2: PostgreSQL (Production setup)

# Clone the repository
git clone https://github.com/MHSanaei/3x-ui.git
cd 3x-ui

# Copy environment file and configure
cp env.example .env
# Edit .env file with your PostgreSQL settings

# Start with PostgreSQL
docker-compose -f docker-compose.postgresql.yml up -d

🔧 Configuration

Environment Variables

Copy env.example to .env and modify according to your needs:

cp env.example .env

Key variables:

Variable	Default	Description
DB_TYPE	sqlite	Database type: sqlite or postgres
DB_HOST	localhost	PostgreSQL host
DB_PORT	5432	PostgreSQL port
DB_NAME	x_ui	Database name
DB_USER	x_ui	Database user
DB_PASSWORD	-	Database password (required for PostgreSQL)
XUI_PORT	2053	3X-UI web interface port
XUI_SUB_PORT	2096	Subscription port

Database Types

SQLite (Default)

• Pros: Simple setup, no additional containers, good for small-medium loads
• Cons: Limited concurrent connections, single file storage
• Use case: Personal use, small teams, development

PostgreSQL

• Pros: High performance, concurrent connections, ACID compliance, scalability
• Cons: More complex setup, additional container
• Use case: Production environments, high load, multiple users

🚀 Deployment Options

1. SQLite Deployment

# Basic SQLite setup
docker-compose up -d

# Check logs
docker-compose logs -f 3x-ui

2. PostgreSQL Deployment

# Set environment variables
export DB_PASSWORD="your_secure_password_here"

# Start PostgreSQL setup
docker-compose -f docker-compose.postgresql.yml up -d

# Check all services
docker-compose -f docker-compose.postgresql.yml ps

3. PostgreSQL with Admin Interface

# Start with PgAdmin for database management
docker-compose -f docker-compose.postgresql.yml --profile admin up -d

# Access PgAdmin at http://localhost:5050
# Default login: admin@example.com / admin_password

4. External PostgreSQL

# Configure .env for external database
cat > .env << EOF
DB_TYPE=postgres
DB_HOST=your-postgres-server.com
DB_PORT=5432
DB_NAME=x_ui_production
DB_USER=x_ui_user
DB_PASSWORD=your_external_db_password
DB_SSLMODE=require
EOF

# Start only 3X-UI container
docker-compose up -d

🔍 Monitoring and Maintenance

Health Checks

All services include health checks:

# Check service health
docker-compose ps

# View health check logs
docker inspect --format='{{json .State.Health}}' 3x-ui

Logs

# View 3X-UI logs
docker-compose logs -f 3x-ui

# View PostgreSQL logs
docker-compose -f docker-compose.postgresql.yml logs -f postgres

# View all logs
docker-compose -f docker-compose.postgresql.yml logs -f

Database Management

Backup PostgreSQL

# Create backup
docker-compose -f docker-compose.postgresql.yml exec postgres pg_dump -U x_ui x_ui > backup.sql

# Restore backup
docker-compose -f docker-compose.postgresql.yml exec -T postgres psql -U x_ui x_ui < backup.sql

Backup SQLite

# SQLite backup
docker-compose exec 3x-ui cp /etc/x-ui/x-ui.db /etc/x-ui/x-ui.db.backup
docker cp 3x-ui:/etc/x-ui/x-ui.db.backup ./x-ui-backup.db

🔧 Troubleshooting

Common Issues

PostgreSQL Connection Failed

# Check PostgreSQL is running
docker-compose -f docker-compose.postgresql.yml ps postgres

# Check PostgreSQL logs
docker-compose -f docker-compose.postgresql.yml logs postgres

# Test connection manually
docker-compose -f docker-compose.postgresql.yml exec postgres psql -U x_ui -d x_ui -c "SELECT 1;"

3X-UI Won't Start

# Check 3X-UI logs
docker-compose logs 3x-ui

# Check database environment
docker-compose exec 3x-ui cat /etc/x-ui/db.env

# Restart services
docker-compose restart

Port Conflicts

# Change ports in .env file
echo "XUI_PORT=3053" >> .env
echo "XUI_SUB_PORT=3096" >> .env

# Restart with new ports
docker-compose up -d

Performance Tuning

PostgreSQL Optimization

The PostgreSQL container is pre-configured with optimized settings for 3X-UI workload:

• max_connections=200
• shared_buffers=256MB
• effective_cache_size=1GB
• work_mem=4MB

For high-load environments, consider:

1. Increase resources:

   deploy:
     resources:
       limits:
         memory: 2G
         cpus: '1.0'
   

2. Use external PostgreSQL with dedicated hardware

3. Enable connection pooling (PgBouncer)

🔒 Security Considerations

Production Checklist

• Change default passwords in .env
• Use strong, unique passwords
• Enable SSL for PostgreSQL (DB_SSLMODE=require)
• Restrict network access (firewall rules)
• Regular backups
• Monitor logs for suspicious activity
• Keep containers updated

Network Security

# Example: Restrict PostgreSQL access
services:
  postgres:
    ports:
      - "127.0.0.1:5432:5432"  # Only localhost access

📊 Monitoring

Prometheus Metrics (Optional)

Add monitoring stack:

# Add to docker-compose.postgresql.yml
  prometheus:
    image: prom/prometheus
    ports:
      - "9090:9090"
    
  grafana:
    image: grafana/grafana
    ports:
      - "3000:3000"

🔄 Migration

SQLite to PostgreSQL

1. Backup SQLite data:

   docker-compose exec 3x-ui cp /etc/x-ui/x-ui.db /etc/x-ui/backup.db
   

2. Export data (manual process - depends on your data structure)

3. Switch to PostgreSQL:

   # Update .env
   echo "DB_TYPE=postgres" >> .env
   
   # Start PostgreSQL
   docker-compose -f docker-compose.postgresql.yml up -d
   

4. Import data (application will create tables automatically)

PostgreSQL to SQLite

1. Export PostgreSQL data
2. Switch to SQLite in .env
3. Import data

📞 Support

• Issues: GitHub Issues
• Documentation: Main README
• Community: Telegram

📝 Examples

Development Setup

# Quick development setup with SQLite
git clone https://github.com/MHSanaei/3x-ui.git
cd 3x-ui
docker-compose up -d

Production Setup

# Production setup with PostgreSQL
git clone https://github.com/MHSanaei/3x-ui.git
cd 3x-ui

# Configure environment
cat > .env << EOF
DB_TYPE=postgres
DB_PASSWORD=$(openssl rand -base64 32)
XUI_PORT=2053
XUI_SUB_PORT=2096
HOSTNAME=$(hostname)
EOF

# Deploy
docker-compose -f docker-compose.postgresql.yml up -d

# Verify
docker-compose -f docker-compose.postgresql.yml ps

High Availability Setup

For HA setups, consider:

• External PostgreSQL cluster
• Load balancer for 3X-UI instances
• Shared storage for certificates
• Monitoring and alerting