How to Self-Host Cypht with Docker Compose

What Is Cypht?

Cypht is a lightweight, modular webmail client that aggregates multiple email accounts into a single unified inbox. Unlike traditional webmail clients that connect to one mail server, Cypht lets you view Gmail, Outlook, your self-hosted Mailcow, and any other IMAP account together. It also includes an RSS feed reader and contact management built in.

Updated February 2026: Verified with latest Docker images and configurations.

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 512 MB of free RAM (1 GB recommended)
• 2 GB of free disk space
• An IMAP email account to connect

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  cypht:
    image: cypht/cypht:2.7.0
    container_name: cypht
    restart: unless-stopped
    ports:
      - "8080:80"
    environment:
      # Database
      - DB_CONNECTION_TYPE=host
      - DB_DRIVER=mysql
      - DB_HOST=cypht-db
      - DB_NAME=cypht
      - DB_USER=cypht
      - DB_PASS=${DB_PASSWORD}
      # Authentication — database-backed
      - AUTH_TYPE=DB
      - SESSION_TYPE=DB
      - USER_CONFIG_TYPE=DB
      # Initial admin user
      - AUTH_USERNAME=${ADMIN_USER}
      - AUTH_PASSWORD=${ADMIN_PASSWORD}
      # Storage
      - USER_SETTINGS_DIR=/var/lib/hm3/users
      - ATTACHMENT_DIR=/var/lib/hm3/attachments
    volumes:
      - cypht_users:/var/lib/hm3/users
      - cypht_attachments:/var/lib/hm3/attachments
    depends_on:
      cypht-db:
        condition: service_healthy

  cypht-db:
    image: mariadb:10.11
    container_name: cypht-db
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=${DB_ROOT_PASSWORD}
      - MYSQL_DATABASE=cypht
      - MYSQL_USER=cypht
      - MYSQL_PASSWORD=${DB_PASSWORD}
    volumes:
      - cypht_db:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  cypht_users:
  cypht_attachments:
  cypht_db:

Create a .env file alongside:

# Database passwords — generate with: openssl rand -hex 16
DB_PASSWORD=CHANGE_ME_TO_STRONG_PASSWORD
DB_ROOT_PASSWORD=CHANGE_ME_TO_DIFFERENT_PASSWORD

# Admin credentials — change before first start
ADMIN_USER=admin
ADMIN_PASSWORD=CHANGE_ME_IMMEDIATELY

Start the stack:

docker compose up -d

Initial Setup

1. Navigate to http://your-server:8080
2. Log in with the credentials from your .env file (admin / your password)
3. Go to Servers → Add an IMAP Server
4. Enter your email provider’s IMAP settings (e.g., imap.gmail.com:993 with TLS)
5. Add the corresponding SMTP server for sending
6. The unified inbox will show messages from all connected accounts

Adding Email Accounts

For each account, you need the IMAP and SMTP server details:

Provider	IMAP Server	SMTP Server
Gmail	imap.gmail.com:993 (TLS)	smtp.gmail.com:587 (STARTTLS)
Outlook	outlook.office365.com:993 (TLS)	smtp.office365.com:587 (STARTTLS)
Self-hosted	Your mail server hostname	Your mail server hostname

Gmail requires an App Password if 2FA is enabled.

Configuration

Authentication Modes

Cypht supports several authentication backends:

Mode	Use Case
DB	Built-in user management (default)
IMAP	Authenticate against an IMAP server directly
LDAP	Connect to Active Directory or OpenLDAP
dynamic	Let users add any IMAP server at login

For IMAP authentication, set:

- AUTH_TYPE=IMAP
- IMAP_AUTH_SERVER=imap.example.com
- IMAP_AUTH_PORT=993
- IMAP_AUTH_TLS=true

Module Management

Cypht uses a modular architecture. Key modules include:

Module	Function
imap	IMAP email support
smtp	Outbound email
feeds	RSS/Atom feed reader
contacts	Contact management
sievefilters	Server-side email filtering
calendar	Calendar integration
2fa	Two-factor authentication
themes	Visual theme switching

Enable or disable modules via the CYPHT_MODULES environment variable.

Reverse Proxy

Cypht serves on port 80 inside the container. Configure your reverse proxy to forward HTTPS traffic:

location / {
    proxy_pass http://cypht:80;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    client_max_body_size 60m;
}

The client_max_body_size directive is important for email attachments. For detailed setup, see Reverse Proxy Setup.

Backup

Back up the MariaDB database and user configuration:

# Database backup
docker exec cypht-db mysqldump -ucypht -p"$DB_PASSWORD" cypht > cypht-backup-$(date +%Y%m%d).sql

# User settings backup
docker cp cypht:/var/lib/hm3/users ./cypht-users-backup

For a comprehensive backup strategy, see Backup Strategy.

Troubleshooting

Cannot Connect to IMAP Server

Symptom: “Connection refused” or timeout when adding an email account. Fix: Verify the IMAP server address and port. For Gmail, you need an App Password (not your regular password). Ensure outbound connections on ports 993 (IMAP) and 587 (SMTP) aren’t blocked by your firewall.

Attachments Fail to Download

Symptom: Clicking attachment links returns errors or empty files. Fix: Check that the ATTACHMENT_DIR volume is mounted and writable. If using a reverse proxy, ensure client_max_body_size is set to at least 60 MB.

Database Connection Refused on First Start

Symptom: Cypht container restarts repeatedly with database errors. Fix: MariaDB takes 10–20 seconds to initialize. The depends_on with service_healthy should handle this, but if the health check is too aggressive, increase the start_period.

RSS Feeds Not Updating

Symptom: Feed items are stale or missing. Fix: Feeds refresh on page load by default. For background updates, set up a cron job calling the Cypht feed update endpoint, or increase the feed refresh interval in settings.

Resource Requirements

• RAM: 150 MB idle, 300–500 MB with multiple accounts active
• CPU: Low — runs well on single-core systems
• Disk: 200 MB for the application, plus attachment storage

Verdict

Cypht fills a specific niche well: aggregating multiple email accounts into one lightweight web UI. If you manage several email accounts across providers and want a single pane of glass, Cypht is the right tool. It’s significantly lighter than Roundcube or Snappymail, but also less feature-rich as a standalone webmail client. For a full-featured webmail experience with one mail server, Roundcube is the better choice. For email aggregation across providers, Cypht is unmatched in the self-hosted space.

Related

• Snappymail vs Cypht: Which Should You Self-Host?
• How to Self-Host Roundcube
• How to Self-Host Snappymail
• Roundcube vs Snappymail
• Self-Hosted Alternatives to Gmail Web Interface
• Best Self-Hosted Email Servers
• Docker Compose Basics
• Reverse Proxy Setup