Launch Cerb in Docker
Pre-built container images in an ideal environment
Install Docker
First, make sure Docker Desktop (desktops) or the Docker Engine (servers) is installed.
Launch Cerb
Option 1: Docker Hub (Production)
Cerb is available as a pre-built container image for amd64
or arm64
on Docker Hub. It must be paired with a web server that supports the FastCGI protocol (e.g. Caddy, nginx, Apache, IIS).
This repository provides several usage examples. For example:
git checkout https://github.com/cerb/cerb-docker/
# ... or download + unzip: https://github.com/cerb/cerb-docker/archive/refs/heads/main.zip
cd cerb-docker/cerb-caddy-mysql
vi .env
docker compose up --build
The cerb
container listens on port :9000
using FastCGI and must not be exposed to the public network. The container is configured using environment variables:
ENV | |
---|---|
CERB_AUTHORIZED_IPS |
A comma-separated list of IPv4 addresses or subnets that can access /cron and /update without a session. |
CERB_INSTALL |
If yes the /install/ path is available; otherwise it is blocked. Only enable during installation and disable afterward. |
MYSQL_HOST |
The database server hostname. This is created for you in the cerb-caddy-mysql example, but should be a dedicated server like Amazon RDS in production. |
MYSQL_DATABASE |
The database name. Use CREATE DATABASE cerb CHARACTER SET utf8mb4 if using an external database server. |
MYSQL_USER |
The database user with GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES . |
MYSQL_PASSWORD |
The database user's password. |
The container uses the /mnt/storage/
path for persistent data. In the example a local Docker volume binds to the path, but in production you should bind a shared filesystem like Amazon EFS, NFS, or GlusterFS. This allows you to scale containers horizontally.
The cerb-caddy-mysql example above provides additional configuration options:
ENV | |
---|---|
CERB_VERSION |
The Cerb versioned image tag to use. Use tags like 11 for 11.x, 11.1 for 11.1.x, or 11.1.0 for a specific version. The latest tag always points to the latest stable version. |
CERB_HOSTNAME |
If localhost a self-signed SSL certificate is generated; otherwise a LetsEncrypt certificate is automatically generated. Be sure the DNS for this hostname points to your server. Ports :80 and :443 must be exposed to the public network for LetsEncrypt to work. |
CERB_PORT |
The HTTP port. This should be 80 in production, but can be something like 8080 for testing. |
CERB_PORT_SSL |
The HTTPS/TLS port. This should be 443 in production, but can be something like 8443 for testing. |
A docker-compose.yml
file is provided for reference and testing. In production, you should use a container orchestration service like Amazon ECS/Fargate, Google Cloud Run, Azure Containers, or Kubernetes.
You can use the cerb example to build your own customized image.
Option 2: GitHub (Development, Testing)
The Cerb source code ships with a Docker configuration for local evaluation, development, and testing. This creates preconfigured containers for Nginx (web server), PHP/FPM (code), and MySQL (database).
You can edit files in your local filesystem and the changes will be reflected instantly within the containers.
By default, data is stored in two volumes (one for the database and the other for the ./storage/
directory). A virtual network is created to connect the containers.
Starting local containers with Docker Compose
Navigate to the directory where you want to install a copy of Cerb. Then run the following commands:
git clone -b v11.0 https://github.com/cerb/cerb-release.git v11.0
# ... or download + unzip: https://github.com/cerb/cerb-release/archive/refs/heads/v11.0.zip
cd v11.0
cd install/docker
docker compose up --build
It will take a few minutes to build the container images the first time you run them. Afterward, the containers will start almost instantly.
Once the containers are running, open your browser to: http://localhost/
The guided installer will finish installing Cerb based on your needs. For testing we recommend disabling outbound email when prompted (this can always be re-enabled later). At the end of the installer you can also choose "Demo" mode to have test data to experiment with.
Updating Cerb
git stash
git pull origin --rebase
git stash pop
Changing the web server port
If you're already using port 80
for a different project, you can bind Cerb to a different port (e.g. 8080
) by editing the docker-compose.yml
file before running docker compose up
.
services:
web:
image: nginx:latest
ports:
- "8080:80"
...
Connecting to the MySQL console
docker exec -it cerb-mysql-1 mysql -u root -p cerb
The default password is s3cr3t
.
Stopping the containers
To pause the containers, use the Ctrl+C
keyboard shortcut or stop them from Docker Desktop.
Resume them later with docker compose up --build
or the play button in Docker Desktop.
Deleting containers
To delete the containers and their data, use the command:
docker compose down --volumes