Install Zimphony Webmail

Install Docker Engine

For Ubuntu 22.04, install Docker Engine from the official Docker repository. Review the official Docker Ubuntu installation guide ↗ before running commands on a production host.

sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io

Install Docker Compose plugin

Docker Compose v2 uses the docker compose command. Install the Compose plugin from the same official Docker repository.

sudo apt-get update
sudo apt-get install -y docker-compose-plugin
docker compose version

Prepare the package

Create a release directory on the host, extract the supplied Zimphony package there, and work from that package directory. Keep the original package archive and any provided SHA256 checksum available for upgrade and rollback review.

sudo mkdir -p /opt/zimphony-webmail
cd /opt/zimphony-webmail
sudo unzip /path/to/zimphony-webmail-[REDACTED].zip
cd zimphony-webmail-[REDACTED]

Do not rename a release directory in a way that hides which package is installed. Do not copy secrets into the Docker image, frontend bundle, or Git repository.

Configure environment safely

Environment files and Docker secrets must stay on the host and in backend-only runtime configuration. Secrets must not be baked into images, committed to Git, copied into frontend.env, or exposed to the browser/client bundle.

Examples of sensitive backend-only values include LICENSE_CHECK_SIGNING_SECRET, ZIMPHONY_LICENSE_KEY, Zimbra credentials, and database settings.

APP_HOST=[APP_HOST]
PRIMARY_DOMAIN=[PRIMARY_DOMAIN]
ADMIN_EMAIL=[ADMIN_EMAIL]
LICENSE_SERVER_URL=[LICENSE_SERVER_URL]
LICENSE_CHECK_SIGNING_SECRET=[REDACTED]
ZIMPHONY_LICENSE_KEY=[REDACTED]
ZIMBRA_ADMIN_EMAIL=[ADMIN_EMAIL]
ZIMBRA_ADMIN_PASSWORD=[REDACTED]
DATABASE_URL=[REDACTED]

Use [REDACTED] in documentation. Do not use masked strings such as ******** copied from a real credential field, because they can be mistaken for evidence of a real secret.

Start the package

Validate the Compose file, start the package, and inspect the running services.

docker compose config --services
docker compose up -d
docker compose ps

The service list should include:

backend
frontend

The service list should not include:

admin-frontend

First-run initialization

After the containers are running, complete the first-run checks before handing the installation to users. Confirm the frontend, backend health endpoint, Domain Admin Portal route, license state for paid editions, and Zimbra connectivity.

For Domain Admin Portal access, open https://[APP_HOST]/admin and then continue to Enable Domain Admin Access for the intended administrative mailbox.

GAL/directory initial sync

Autocomplete uses a local GAL snapshot. Run the initial directory sync after the first installation so the backend can build the first local snapshot.

docker compose exec backend zimphony-directory-sync

The sync reads users and distribution lists, then creates or updates the local snapshot atomically. If a sync fails, Zimphony keeps the last-known-good snapshot. Public logs and documentation should show only numeric summaries, not customer directory dumps.

Expected summary shape:

status=success
users=<number>
distribution_lists=<number>
duration_ms=<number>

The regular schedule is 02:00 and 12:00 in the installation timezone.

• Directory sync does not run on login.
• Directory sync does not run merely because Compose starts.
• Directory sync does not run on every autocomplete keystroke.
• Autocomplete searches the local snapshot.

Health checks

When local access to the Docker host is available, check the frontend and backend directly:

curl -fsS http://127.0.0.1:3000/
curl -fsS http://127.0.0.1:8000/health

If local access is not available, use the public HTTPS host for the installation:

https://[APP_HOST]/
https://[APP_HOST]/admin

Do not replace these placeholders with a real customer URL in public documentation.

Admin and Webmail access

• https://[APP_HOST]/ opens Zimphony Webmail through the frontend container.
• https://[APP_HOST]/admin opens the Domain Admin Portal through the same frontend container.
• /api/* and /api/admin/* must route to the backend container.

Domain Admin Portal is domain-scoped. It is not a customer self-service license portal and it must not expose secrets or deployment-wide tenant data to the wrong context.

Upgrade procedure

1. Back up the database, backend data, Docker volumes, and host environment files.
2. Verify the new artifact SHA256 checksum against the supplied release information.
3. Extract the new package into a new release directory.
4. Preserve customer environment files and data; do not copy secrets into Git or images.
5. Validate the Compose service list.
6. Start the updated backend and frontend.
7. Verify local health checks.
8. Verify https://[APP_HOST]/admin and https://[APP_HOST]/.

# From the new package directory, after backup and SHA256 verification:
docker compose config --services
docker compose up -d --build backend frontend
docker compose ps

Rollback

Rollback by returning to the previous package directory while preserving the same customer volumes, database, and environment files unless the release notes instruct otherwise.

# From the previous package directory:
docker compose up -d
docker compose ps

Do not use these commands as a rollback shortcut:

docker compose down -v
docker system prune -a
docker volume prune