Skip to main content

Installation

This guide walks you through installing OPBX using Docker Compose. This is the recommended method for both development and production deployments.

Prerequisites​

Before starting, ensure you have:

  • Met all system requirements
  • Docker and Docker Compose installed
  • Git installed
  • A working internet connection (for downloading images)
Estimated Time

The installation process typically takes 10-15 minutes, depending on your internet connection.

Step 1: Clone the Repository​

Clone the OPBX repository to your local machine:

git clone https://github.com/greenfieldtech-nirs/opbx
cd opbx

This creates an opbx directory containing all the necessary files.

Step 2: Environment Configuration​

Copy the Example Environment File​

cp .env.example .env

Edit Required Variables​

Open .env in your text editor and configure the following required variables:

# Application
APP_NAME="OPBX"
APP_ENV=production
APP_DEBUG=false
APP_URL=http://localhost

# Database
DB_DATABASE=opbx
DB_USERNAME=opbx
DB_PASSWORD=your_secure_password_here
Security Note

Change all default passwords and secrets. Never use default credentials in production.

Environment Variables Reference​

VariableRequiredDescription
APP_URLYesThe URL where OPBX will be accessed
DB_PASSWORDYesMySQL database password
APP_PORTNoHost port for nginx (default: 80)
Cloudonix Configuration

Cloudonix integration is configured in the OPBX admin UI after login, not via environment variables. See Cloudonix Integration for details.

Port Configuration

If port 80 is already in use on your system, change APP_PORT in .env to use a different port (e.g., 8080).

Step 3: Start the Services​

Build and Start All Services​

docker compose up -d

This command:

  • Downloads required Docker images
  • Builds custom images if needed
  • Creates and starts all containers
  • Sets up the network and volumes
First Run

The first startup takes longer as Docker downloads images (2-3 GB total). Subsequent starts are much faster.

Monitor the Startup​

Check the status of containers:

docker compose ps

You should see all services in the "running" state:

NAME              IMAGE                           STATUS
opbx_nginx        nginx:alpine                    Up 2 minutes
opbx_app          opbxcloudonixcom-app            Up 2 minutes
opbx_mysql        mysql:8.0                       Up 2 minutes
opbx_redis        redis:7-alpine                  Up 2 minutes
opbx_frontend     opbxcloudonixcom-frontend       Up 2 minutes
opbx_docusaurus   opbxcloudonixcom-docusaurus     Up 2 minutes

Check Logs​

If any service fails to start, check the logs:

# All services
docker compose logs

# Specific service
docker compose logs app
docker compose logs mysql

# Follow logs in real-time
docker compose logs -f

Step 4: Verify the Installation​

Access URLs​

Once all services are running, access OPBX at:

ServiceURLDescription
Main Applicationhttp://localhost/uiReact frontend
APIhttp://localhost/apiLaravel API
Documentationhttp://localhost/docsThis documentation

Health Checks​

Verify the system is healthy:

# General health check
curl http://localhost/api/health

# Expected response:
{"status":"ok","timestamp":"2026-03-04T12:00:00Z"}

Container Status​

Verify all containers are healthy:

docker compose ps --format "table {{.Name}}\t{{.Status}}\t{{.Health}}"

Step 5: Database Initialization​

On first run, the database migrations will execute automatically. Verify:

docker compose exec app php artisan migrate:status

You should see a list of migrations with "Ran" status.

note

If migrations fail, check MySQL is ready:

docker compose logs mysql

Services Overview​

Docker Compose starts the following services:

ServiceContainer NamePurposeInternal Port
Nginxopbx_nginxReverse proxy80
Laravelopbx_appAPI backend9000
Reactopbx_frontendFrontend dev server3000
MySQLopbx_mysqlDatabase3306
Redisopbx_redisCache/Queue6379
MinIOopbx_minioObject storage9000
Soketiopbx_websocketWebSocket server6001
Docusaurusopbx_docusaurusDocumentation80

Troubleshooting​

Port Conflicts​

Error: bind: address already in use

Solution: Another service is using port 80. Either:

  1. Stop the conflicting service, OR
  2. Change the port in .env:
APP_PORT=8080  # Use port 8080 instead of 80

Then restart the containers:

docker compose up -d

Permission Denied​

Error: permission denied while trying to connect to Docker daemon

Solution: Add your user to the docker group:

sudo usermod -aG docker $USER
# Log out and back in

MySQL Connection Failed​

Error: Connection refused or timeout

Solution: Wait for MySQL to fully start (can take 30-60 seconds on first run):

# Check MySQL logs
docker compose logs mysql

# Wait for MySQL to be ready
docker compose exec mysql mysqladmin ping

Frontend Build Fails​

Error: npm ERR! code EUSAGE or build errors

Solution: Clear and rebuild:

# Clear volumes and rebuild
docker compose down -v
docker compose build --no-cache
docker compose up -d

Out of Disk Space​

Error: no space left on device

Solution: Clean up Docker:

# Remove unused images and volumes
docker system prune -a --volumes

# Check disk usage
docker system df

Updating OPBX​

To update to the latest version:

# Pull latest changes
git pull origin main

# Rebuild containers
docker compose down
docker compose build --no-cache
docker compose up -d

# Run migrations
docker compose exec app php artisan migrate

Stopping OPBX​

To stop all services:

# Stop containers (preserves data)
docker compose stop

# Stop and remove containers (preserves volumes)
docker compose down

# Stop and remove everything (⚠️ DELETES ALL DATA)
docker compose down -v

Next Steps​

Your OPBX installation is now running! Continue to:

→ First Login to create your first organization and admin user.

→ Cloudonix Pairing to enable VoIP functionality.

Uninstallation​

To completely remove OPBX:

# Stop and remove containers
docker compose down -v

# Remove source code (optional)
cd ..
rm -rf opbx
Data Loss

docker compose down -v permanently deletes all data, including:

  • Database contents
  • Call recordings
  • User accounts
  • Configuration

Make sure to back up any important data before running this command.