Ubersmith and Docker

Ubersmith runs as a set of Docker containers. The database, web server, mail server, search engine, and other services each run in their own container.

Requirements

Ubersmith runs on Linux (Rocky, Ubuntu, or Debian). Docker for Mac isn't supported. The host needs:

• Docker Engine 20.10 or later, with the Docker Compose V2 plugin (the docker compose command, not the older standalone docker-compose).
• At least 4 CPU cores and 8 GB of RAM. 8 cores and 16 GB or more is recommended.
• At least 100 GB of free disk space, plus more room for data growth.
• Ports 80, 443, 25, and 4321 open on the host.
• Internet access to pull container images from ghcr.io/teamubersmith, and credentials for that registry.

Filesystem Locations

Ubersmith is normally installed in /usr/local/ubersmith. This directory has the following subdirectories:

• app/custom/ — holds custom files, such as service, order, and device modules. Any file in this directory is copied to the webroot of the web container when the container starts or restarts. The subfolders include/{service,order,device}_modules show where to put custom module class files. The plugins subfolder holds custom plugins.
• app/patches/ — holds patch files applied on top of the installed Ubersmith version.
• conf/mysql/ — holds ubersmith.cnf, which configures or overrides specific MySQL variables. Variables are updated when the db container restarts.
• conf/ssl/ — holds the .key and .pem files used by the web, mail, and pmm containers. These file names are important; a service with an unexpected file name fails to start, or starts with TLS disabled. To include a CA bundle, place the leaf certificate in the .pem file, then add the CA bundle. Restart the web and mail containers after changing certificates.
• conf/httpd/, including conf/httpd/sites-enabled/ — holds the Apache virtual host configuration for Ubersmith. If a deployment supports multiple brands, each brand gets its own virtual host file here.
• conf/cron/ — empty by default. A file placed here overrides the matching file in /etc/cron.d inside the cron container. This is only needed to override a default Ubersmith cron task.
• conf/certbot/ — holds Let's Encrypt state (lib, etc, etc/renewal-hooks/deploy, log) for the certbot container.
• conf/mail/, conf/rwhois/, conf/sso/, conf/falco/ — hold configuration for the mail, rwhois, SSO, and falco containers.
• logs/ubersmith/ — holds the Apache access and error logs. As of Ubersmith 5.x, container logs are sent to systemd's journal instead of files here; view them with journalctl (see Logging below).

Adding Custom Files

After adding custom files to app/custom/, recreate the Ubersmith containers so the new files are picked up:

# cd /usr/local/ubersmith
# docker compose rm -sf
# ./ubersmith_start.sh

This is only needed when adding new files. Changes to existing files are reflected immediately.

The Containers

Running containers are named ubersmith-<service>-<number>, using the Docker Compose project name ubersmith — for example, the web container is ubersmith-web-1. Refer to a container by its short service name with docker compose, for example docker compose start web.

Core services:

Appliance services (for the Ubersmith Appliance):

Docker Compose

Ubersmith uses Docker Compose to manage its containers. Two files in /usr/local/ubersmith control this: docker-compose.yml and docker-compose.override.yml. Make deployment-specific changes in the override file, since docker-compose.yml can be replaced when Ubersmith is upgraded.

The commands below assume Ubersmith is installed in /usr/local/ubersmith. If it's installed elsewhere, add -p ubersmith to each docker compose command.

Starting Ubersmith:

# cd /usr/local/ubersmith
# docker compose up -d

Stopping Ubersmith:

# cd /usr/local/ubersmith
# docker compose stop

Restarting specific containers:

# cd /usr/local/ubersmith
# docker compose restart web mail

Checking status:

# cd /usr/local/ubersmith
# docker compose ps

Configuring an External Database Server

By default, Ubersmith connects to its own db container. To use a different database host, edit the web service's environment section in docker-compose.override.yml:

environment:
  MYSQL_PASSWORD: your_database_password
  DATABASE_HOST: database.yourdomain.com

Confirm the database's username and database name match what the external server expects, then recreate the containers:

# cd /usr/local/ubersmith
# docker compose rm -sf
# ./ubersmith_start.sh

Making a Backup

Starting the backup container runs Percona xtrabackup and takes a live database snapshot. Output is shown in the terminal. The backup is stored, uncompressed, in /usr/local/ubersmith/backup.

# cd /usr/local/ubersmith
# docker compose up backup

The db container listens on the host's loopback interface (127.0.0.1:3306) by default. Database credentials can be found in /usr/local/ubersmith/docker-compose.yml. These credentials also work with other backup tools, such as mysqldump.

Logging

As of Ubersmith 5.x, container logs are sent to systemd's journal rather than to log files. View them with journalctl. For example, to view the mail container's logs:

# journalctl -f -t ubersmith/mail

Troubleshooting

Container Won't Start

Most containers use Docker's unless-stopped restart policy, so a crashed container normally restarts on its own. php and some other containers wait for rsyslog to report healthy before they start; if rsyslog doesn't come up, dependent containers stay pending rather than starting.

If a container won't start, contact Ubersmith support for help. To investigate further yourself, start the container in the foreground to see its startup output. For example, if web isn't starting because of a problem in the Apache configuration under /usr/local/ubersmith/conf/httpd:

# cd /usr/local/ubersmith
# docker compose up web

This shows the container's output, including any error message, until the container exits. Once the problem is fixed, start the container normally:

# cd /usr/local/ubersmith
# docker compose up -d web

Restarting Docker

If other troubleshooting steps don't resolve a networking or firewall issue, restart Docker itself:

# service docker restart

This recreates the firewall rules Docker needs for both external and inter-container traffic. Ubersmith's containers are set to start automatically when Docker starts.