Getting Started

Install Zimphony Webmail

Take a prepared Linux host from package download to a working Zimphony Webmail installation.

Before you start

Prepare the host, public hostname, and connection details before running the installer.

General requirements

64-bit Linux host
Docker
Caddy
Zimbra IP address or hostname
Zimbra Admin email and password
Webmail hostname with DNS configured

Edition-specific values

Webmail Free requires no license key.

Paid editions also require:

LICENSE_SERVER_URL=https://license.zimphony.com
ZIMPHONY_LICENSE_KEY=<provided-license-key>
LICENSE_CHECK_SIGNING_SECRET=<provided-signing-secret>

LICENSE_SERVER_URL normally keeps the default value. The License Key and Signing Secret are supplied for the paid deployment.

01
Install Linux
Prepare a 64-bit Linux environment capable of running the required Docker stack. Complete the operating-system setup and updates before continuing.
02
Install Docker
Docker must be available before installing Zimphony. Use the installation instructions for your Linux distribution in the official Docker Engine documentation .
03
Install Caddy
Caddy provides the public HTTPS and reverse-proxy layer. Install it using the instructions for your Linux distribution in the official Caddy documentation .

Configure Caddy

Use this deployment example as the basis for your Caddyfile. Replace mail.example.com with the actual Zimphony Webmail hostname.

mail.example.com {
    encode zstd gzip

    handle_path /api/admin/* {
        reverse_proxy 127.0.0.1:8000
    }

    handle /calendar/oauth/callback {
        reverse_proxy 127.0.0.1:8000
    }

    handle /calendar/webhook {
        reverse_proxy 127.0.0.1:8000
    }

    handle_path /api/* {
        reverse_proxy 127.0.0.1:8000
    }

    @admin path /admin /admin/*
    handle @admin {
        reverse_proxy 127.0.0.1:3000
    }

    handle {
        reverse_proxy 127.0.0.1:3000
    }
}

05
Download Zimphony Webmail
Download the appropriate Zimphony Webmail release package supplied for your edition. Webmail Free does not require a license key.
06
Prepare the package
Create /opt/zimphony-webmail/ as the parent directory for Zimphony releases, then extract the release ZIP inside it:
```
sudo mkdir -p /opt/zimphony-webmail

cd /opt/zimphony-webmail

sudo unzip /path/to/zimphony-webmail-xxxx.zip

cd zimphony-webmail-xxxx
```
The ZIP must create a release-specific directory such as zimphony-webmail-xxxx/. Because you are already in /opt/zimphony-webmail, enter the newly extracted release directory with the relative path shown before continuing to the installer. The ZIP filename and directory name vary by Edition and release timestamp.
Do not rename the release directory to /opt/zimphony-webmail, and do not select an Edition manually from a generic name. Use the ZIP supplied for the intended Edition.
07
Run the installer
```
sudo ./install.sh
```
Answer the installer prompts. Prepare Zimbra values corresponding to these examples:
```
DEFAULT_ZIMBRA_SOAP_URL=https://192.168.1.100:8443/service/soap
ZIMBRA_PROVISIONING_URL=https://192.168.1.100:7071/service/admin/soap
[email protected]
ZIMBRA_ADMIN_PASSWORD=<zimbra-admin-password>
```
Use your deployment's actual Zimbra endpoints and administrator credentials. Paid installations also require the licensing values listed above. Google Connect installations also require the Google Client ID and Client Secret.
08
Complete installation
After the installer questions are complete, installation typically finishes in about five minutes. This timing does not include preparing Linux, Docker, Caddy, DNS, the release package, or installer answers.
09
Verify
Open both endpoints using your actual Webmail hostname:
- https://mail.example.com — verifies Webmail access.
- https://mail.example.com/admin — verifies that the Domain Admin Portal is reachable.
Portal reachability does not authorize every mailbox to sign in. Continue to Enable Domain Admin Access to authorize the intended mailbox.