SuiteCRM Docker Deployment: Containerized CRM Setup Guide

Docker simplifies SuiteCRM deployment by packaging the application, PHP, web server, and database into reproducible containers. Instead of manually configuring a LAMP stack on every server, you define your environment once and deploy it anywhere — development, staging, and production — with identical results.

This guide covers SuiteCRM Docker deployment from scratch: container architecture, Docker Compose configuration, persistent storage, SSL setup, and production optimization.

Why Docker for SuiteCRM

Environment consistency. The same container runs identically on your laptop, CI/CD pipeline, staging server, and production. “Works on my machine” becomes “works everywhere.”

Simplified deployment. A single docker-compose up command provisions SuiteCRM with PHP, Apache/Nginx, MySQL, and all dependencies — no manual package installation.

Easy scaling. Need a test environment? Spin up a second container in minutes. Need to migrate servers? Copy your compose file and volumes.

Isolation. SuiteCRM runs in its own container, isolated from other applications on the same server. PHP version conflicts, library mismatches, and dependency issues disappear.

Container Architecture

A typical SuiteCRM Docker deployment uses two containers:

Application container — runs Apache/Nginx + PHP-FPM with SuiteCRM’s code. Handles web requests and PHP execution.

Database container — runs MySQL or MariaDB. Stores all CRM data in a persistent volume.

For production, consider adding a third container for Redis or Memcached (caching layer) to boost performance.

Docker Compose Setup

Create a docker-compose.yml file that defines both services. The application service should use PHP 8.1+ with Apache, mount a persistent volume for SuiteCRM files (including uploads, custom code, and config), expose ports 80 and 443, and set environment variables for database connection. The database service should use MariaDB 10.6 or MySQL 8.0, mount a persistent volume for data directory, and set root password and database name via environment variables.

Key configuration points: set PHP memory_limit to 512M, enable OPcache with recommended settings (see our performance guide), configure upload_max_filesize and post_max_size to 20M, and ensure the SuiteCRM Scheduler cron runs inside the container every minute.

Persistent Volumes

Volumes ensure data survives container restarts and updates. Mount two critical volumes: one for the SuiteCRM application directory (preserving uploads, custom modules, config files) and one for the MariaDB data directory. Without persistent volumes, all data is lost when containers restart.

SSL/TLS Configuration

For production, add SSL using a reverse proxy container (Nginx or Traefik) that handles HTTPS termination. Use Let’s Encrypt with Certbot for free certificates. The reverse proxy forwards decrypted traffic to the application container on port 80 internally. This is more secure and flexible than configuring SSL inside the application container.

SuiteCRM Scheduler in Docker

SuiteCRM’s workflow engine depends on a cron job running every minute. Inside Docker, you have two approaches: run cron inside the application container (add crontab configuration to the Dockerfile), or run a separate sidecar container that executes the scheduler command on a timer. The sidecar approach is cleaner for production — it separates the web serving process from the background task execution.

Production Optimization

For production Docker deployments, apply these optimizations: use PHP-FPM instead of mod_php for better process management, configure OPcache with validate_timestamps=0 (rebuild container for code changes), set innodb_buffer_pool_size to 50–70% of available RAM in the database container, use Docker health checks to monitor both containers, implement automated backups of both volumes (see our backup guide), and use Docker restart policies (restart: unless-stopped) for resilience.

Updating SuiteCRM in Docker

To upgrade SuiteCRM in a Docker environment: back up both persistent volumes, update the SuiteCRM code in your application volume or rebuild the Docker image with the new version, restart the application container, and run Admin → Repair → Quick Repair and Rebuild. For major version upgrades, test on a staging container first.

When to Use Docker vs Traditional Hosting

Use Docker if your team is comfortable with containerization, you need identical dev/staging/production environments, you run multiple SuiteCRM instances (e.g., for different clients), or you deploy on cloud platforms that favor containers (AWS ECS, Google Cloud Run, Azure Container Instances).

Use traditional hosting if your team isn’t Docker-experienced, you prefer straightforward LAMP administration, or your hosting provider doesn’t support Docker. See our SuiteCRM hosting guide for traditional deployment options.

Docker Compose Best Practices for SuiteCRM

Use named volumes, not bind mounts for production. Named volumes are managed by Docker and perform better on most platforms. Reserve bind mounts for development where you need live code editing.

Pin specific image versions. Never use “latest” tags in production compose files. Pin PHP, MariaDB, and Nginx images to specific versions (e.g., php:8.2-apache, mariadb:10.6) so rebuilds produce identical environments.

Use environment files (.env) for sensitive configuration — database passwords, API keys, and SMTP credentials. Never hardcode secrets in docker-compose.yml. Add .env to .gitignore.

Implement health checks on both containers. The application container should check that PHP-FPM responds on the expected port. The database container should verify MySQL accepts connections. Docker Compose’s depends_on with condition: service_healthy ensures proper startup ordering.

Set resource limits to prevent runaway containers from consuming all server resources. Define CPU and memory limits per container based on your server capacity and expected load.

Log to stdout/stderr rather than files inside containers. This enables Docker’s native log drivers to capture, rotate, and forward logs to centralized logging systems like ELK or Grafana Loki.