Deploy with Docker Compose

This guide will help you deploy OpenPanel using Docker Compose. This method gives you full control over your deployment and is perfect for self-hosting on a VPS or dedicated server.

Prerequisites

• A VPS or server (Docker and Node will be installed automatically if needed)
• At least 2GB RAM (4GB+ recommended)
• Domain name pointing to your server (optional but recommended)
• Basic knowledge of command line

Quick Start

git clone -b self-hosting https://github.com/Openpanel-dev/openpanel.git
cd openpanel/self-hosting

./setup

./start

docker compose ps

docker compose logs -f

./logs

Configuration

Environment Variables

The setup wizard will configure most environment variables automatically. You can manually edit the .env file in the self-hosting directory if needed.

For a complete reference of all available environment variables, see the Environment Variables documentation.

Using Custom Docker Images

If you want to use specific image versions, edit the docker-compose.yml file and update the image tags:

op-api:
  image: lindesvard/openpanel-api:v1.0.0  # Specify version

Scaling Workers

To scale the worker service, set the OP_WORKER_REPLICAS environment variable:

OP_WORKER_REPLICAS=3 docker compose up -d

Or edit the docker-compose.yml file:

op-worker:
  deploy:
    replicas: 3

Managing Your Deployment

OpenPanel comes with several utility scripts to help manage your deployment. All scripts should be run from within the self-hosting directory.

Basic Operations

./start    # Start all OpenPanel services
./stop     # Stop all OpenPanel services
./logs     # View real-time logs from all services

View Logs

View logs from all services:

./logs

Or using Docker Compose directly:

docker compose logs -f

View logs from a specific service:

docker compose logs -f op-api

Stop Services

Stop all services:

./stop

Or using Docker Compose:

docker compose down

Stop services but keep volumes (data persists):

docker compose stop

Restart Services

Restart all services:

./stop && ./start

Or using Docker Compose:

docker compose restart

Restart a specific service:

docker compose restart op-api

Rebuild Services

Rebuild and restart a specific service:

./rebuild op-dashboard

Update OpenPanel

To update to the latest version, use the update script:

./update

This script will:

1. Pull the latest changes from the repository
2. Pull the latest Docker images
3. Restart all services

git pull
docker compose pull
docker compose up -d

Backup and Restore

Backup

Backup your PostgreSQL database:

docker compose exec op-db pg_dump -U postgres postgres > backup.sql

Backup volumes:

docker run --rm -v openpanel_op-db-data:/data -v $(pwd):/backup alpine tar czf /backup/db-backup.tar.gz /data

Restore

Restore PostgreSQL database:

docker compose exec -T op-db psql -U postgres postgres < backup.sql

Troubleshooting

Services Won't Start

1. Check Docker and Docker Compose versions:

   docker --version
   docker compose version

2. Check available disk space:

   df -h

3. Check logs for errors:

   docker compose logs

Database Connection Issues

If services can't connect to the database:

1. Verify the database is healthy:

   docker compose ps op-db

2. Check database logs:

   docker compose logs op-db

3. Verify DATABASE_URL in your .env file matches the service name op-db

Port Conflicts

If ports 80 or 443 are already in use, you can:

1. Change the ports in docker-compose.yml:

   ports:
     - "8080:80"
     - "8443:443"

2. Or stop the conflicting service

Health Check Failures

If health checks are failing:

1. Check if services are actually running:

   docker compose ps

2. Increase health check timeout in docker-compose.yml:

   healthcheck:
     interval: 30s
     timeout: 10s
     retries: 10

Using Your Own Reverse Proxy

If you're using your own reverse proxy (like Nginx or Traefik), you can disable the included Caddy proxy by commenting it out in docker-compose.yml:

# op-proxy:
#   image: caddy:2-alpine
#   ...

Then configure your reverse proxy to forward requests:

• /api/* → op-api:3000
• /* → op-dashboard:3000

Next Steps

• Configure email settings for password resets and invitations
• Set up AI integration for the analytics assistant
• Configure SDK to track events from your applications