savignano/uptrust-gateway repository overview

⁠Uptrust Gateway Docker Image

This is the public docker image for the Uptrust Email Encryption Gateway.

⁠Docker Run Example

Example container run:

docker run --name uptrust-gateway \
  -p 25:25 -p 465:465 -p 587:587 \
  -p 143:143 -p 993:993 \
  -p 8080:8080 \
  -e BACKEND_IMAP_SERVER=imap.backend.local \
  -e BACKEND_IMAP_PORT=993 \
  -e BACKEND_IMAP_SECURITY=enabled \
  -e BACKEND_SMTP_SERVER=smtp.backend.local \
  -e BACKEND_SMTP_PORT=587 \
  -e BACKEND_SMTP_SECURITY=starttls \
  -e BACKEND_SMTP_MTA_SERVER=smtp-mta.backend.local \
  -e TLS_KEYSTORE_TYPE=PEM \
  -e TLS_CERTS=/var/docker/tls/fullchain.pem \
  -e TLS_KEY=/var/docker/tls/private/privkey.pem \
  -v uptrust-conf:/var/opt/uptrust/conf \
  -v uptrust-keystores:/var/opt/uptrust/keystores \
  -v uptrust-logs:/var/opt/uptrust/logs \
  savignano/uptrust-gateway:latest

⁠Docker Compose Example

services:
  uptrust-gateway:
    image: savignano/uptrust-gateway:latest
    container_name: uptrust-gateway
    ports:
      - "25:25"
      - "465:465"
      - "587:587"
      - "143:143"
      - "993:993"
      - "8080:8080"
    environment:
      BACKEND_IMAP_SERVER: imap.backend.local
      BACKEND_IMAP_PORT: "993"
      BACKEND_IMAP_SECURITY: enabled
      BACKEND_SMTP_SERVER: smtp.backend.local
      BACKEND_SMTP_PORT: "587"
      BACKEND_SMTP_SECURITY: starttls
      BACKEND_SMTP_MTA_SERVER: smtp-mta.backend.local
      BACKEND_SMTP_MTA_PORT: "25"
      BACKEND_SMTP_MTA_SECURITY: starttls
      UPTRUST_LOG_LEVEL: WARN
      TLS_KEYSTORE_TYPE: PEM
      TLS_CERTS: /var/docker/tls/fullchain.pem
      TLS_KEY: /var/docker/tls/private/privkey.pem
    volumes:
      - uptrust-conf:/var/opt/uptrust/conf
      - uptrust-keystores:/var/opt/uptrust/keystores
      - uptrust-logs:/var/opt/uptrust/logs
      - ./cacerts:/var/opt/uptrust/cacerts
    restart: unless-stopped

volumes:
  uptrust-conf:
  uptrust-keystores:
  uptrust-logs:

⁠Volumes

• /var/opt/uptrust/conf: runtime configuration files
• /var/opt/uptrust/keystores: public and private key store files
• /var/opt/uptrust/logs: log files
• /var/opt/uptrust/cacerts: (optional) custom CA root certificates

⁠Configuration UI

By default, the configuration can be reached on port 8080. There is no default password. The first time you open the interface you are asked to set a password for the admin user.

It is stored at /var/opt/uptrust/conf/private/pwd, which lives in the conf volume and therefore survives container recreation. If you lose the password, or the file becomes corrupt, delete it and restart the container to be prompted again.

For more infos about configuring Uptrust through the UI, go to the Uptrust Documentation and Help Center⁠.

⁠Environment Variables

⁠Backend mail server

The backend mail server is the mail server that Uptrust acts as a gateway for.

⁠IMAP

This is the backend IMAP server for access to the mailboxes by mail clients.

• BACKEND_IMAP_SERVER (required)
• BACKEND_IMAP_PORT (default 993)
• BACKEND_IMAP_SECURITY (default enabled)

⁠SMTP

This is the backend SMTP server for outgoing mail, used by mail clients to send outgoing mail.

• BACKEND_SMTP_SERVER (required)
• BACKEND_SMTP_PORT (default 587)
• BACKEND_SMTP_SECURITY (default starttls)

⁠SMTP MTA

This is the SMTP server for incoming mail, used by external mail servers
to deliver incoming mail (mail transfer agents).

• BACKEND_SMTP_MTA_SERVER (required)
• BACKEND_SMTP_MTA_PORT (default 25)
• BACKEND_SMTP_MTA_SECURITY (default starttls)

⁠TLS certificates

TLS certificates and keys are used by the Uptrust Gateway server for incoming SMTP and IMAP connections.

They can be provided either combined in a keystore file or as separate certificate files in pem format.

Note that Uptrust requires TLS to be set up, so one of the following configurations is required.

For keystore file format, use:

• TLS_KEYSTORE_TYPE (PKCS12 for p12 or pfx keystore files)
• TLS_KEYSTORE (the keystore file)
• TLS_SECRET (the password required to access the keystore)

For certificate files, use:

• TLS_KEYSTORE_TYPE (must be PEM)
• TLS_CERTS (the file holding the certificate or chain of certificates)
• TLS_KEY (the file holding the server key)
• TLS_SECRET (optional password if the key file is password protected)

⁠Integrate with Let's Encrypt

To use TLS certificates issued by Let's Encrypt for the Uptrust domain, you may run a certbot container alongside uptrust-gateway and share the issued PEM files through a Docker volume.

Use .env file:

UPTRUST_HOSTNAME=mail.example.com

UPTRUST_HOSTNAME is the public hostname of the Uptrust gateway itself. The BACKEND_* hostnames refer to separate upstream mail servers and do not need to match the public certificate hostname.

UPTRUST_HOSTNAME is also the hostname for which Let's Encrypt issues your certificate. You also need to expose the ACME challenge path for Certbot, for example through a reverse proxy serving ./certbot/www. After certificate renewal, restart or recreate the uptrust-gateway container so the gateway reloads the updated certificate files.

Docker Compose setup:

services:
  uptrust-gateway:
    image: savignano/uptrust-gateway:latest
    container_name: uptrust-gateway
    ports:
      - "25:25"
      - "465:465"
      - "587:587"
      - "143:143"
      - "993:993"
      - "8080:8080"
    environment:
      BACKEND_IMAP_SERVER: imap.backend.local
      BACKEND_IMAP_PORT: "993"
      BACKEND_IMAP_SECURITY: enabled
      BACKEND_SMTP_SERVER: smtp.backend.local
      BACKEND_SMTP_PORT: "587"
      BACKEND_SMTP_SECURITY: starttls
      BACKEND_SMTP_MTA_SERVER: smtp-mta.backend.local
      BACKEND_SMTP_MTA_PORT: "25"
      BACKEND_SMTP_MTA_SECURITY: starttls
      UPTRUST_LOG_LEVEL: WARN
      TLS_KEYSTORE_TYPE: PEM
      TLS_CERTS: /etc/letsencrypt/live/${UPTRUST_HOSTNAME}/fullchain.pem
      TLS_KEY: /etc/letsencrypt/live/${UPTRUST_HOSTNAME}/privkey.pem
    volumes:
      - uptrust-conf:/var/opt/uptrust/conf
      - uptrust-keystores:/var/opt/uptrust/keystores
      - uptrust-logs:/var/opt/uptrust/logs
      - ./cacerts:/var/opt/uptrust/cacerts
      - letsencrypt:/etc/letsencrypt:ro
    restart: unless-stopped

  certbot:
    image: certbot/certbot:latest
    container_name: certbot
    volumes:
      - letsencrypt:/etc/letsencrypt
      - ./certbot/www:/var/www/certbot
    command: certonly --webroot -w /var/www/certbot -d ${UPTRUST_HOSTNAME}

volumes:
  uptrust-conf:
  uptrust-keystores:
  uptrust-logs:
  letsencrypt:

⁠Password encryption key

The encryption key used to encrypt passwords in the configuration files.

If missing, a password will be auto-generated and stored at /var/opt/uptrust/conf/private/pwenc.

• UPTRUST_PW_ENC_KEY

⁠Log levels

Log levels can be ERROR, WARN, INFO, DEBUG, TRACE. Beware that log levels DEBUG and TRACE may log secrets and/or confidential data, including email contents.

The logging option variables are:

• DEFAULT_LOG_LEVEL controls the global/root logging
• UPTRUST_LOG_LEVEL controls general Uptrust logging
• UPTRUST_PROTOCOLS_LOG_LEVEL controls general protocol-related logging
• UPTRUST_IMAP_LOG_LEVEL controls IMAP protocol logging only
• UPTRUST_SMTP_LOG_LEVEL controls SMTP protocol logging only
• UPTRUST_CRYPTO_LOG_LEVEL controls cryptography-related logging
• UPTRUST_CONFIG_LOG_LEVEL controls config server protocol logging

Fallback chain:

• DEFAULT_LOG_LEVEL defaults to WARN
• UPTRUST_LOG_LEVEL defaults to INFO
• UPTRUST_PROTOCOLS_LOG_LEVEL defaults to UPTRUST_LOG_LEVEL
• UPTRUST_IMAP_LOG_LEVEL defaults to UPTRUST_PROTOCOLS_LOG_LEVEL
• UPTRUST_SMTP_LOG_LEVEL defaults to UPTRUST_PROTOCOLS_LOG_LEVEL
• UPTRUST_CRYPTO_LOG_LEVEL defaults to UPTRUST_LOG_LEVEL
• UPTRUST_CONFIG_LOG_LEVEL defaults to UPTRUST_LOG_LEVEL

⁠Optional custom trusted root certificates

If required, custom CA certificates can be added to the system and Java truststores.

For best compatibility, mount custom roots in pem format as .crt files into:

• /var/opt/uptrust/cacerts

⁠Ports

The exposed port default configuration of the Uptrust Gateway is

• Port 143 for IMAP with enforced StartTLS
• Port 993 for IMAP over TLS
• Port 587 for SMTP with enforced StartTLS
• Port 465 for SMTP with TLS
• Port 25 for MTA SMTP with opportunistic StartTLS
• Port 8080 for the configuration UI

You can choose to publish all or some of these ports to the same or different ports of the docker host.

⁠Health Check

The container will be in status healthy when the gateway is running and listening on SMTP port 25, otherwise status is set to unhealthy. This check only inspects the local listener state and does not open a health-check connection.

Example how to check the container's health status:

docker inspect -f '{{.State.Health.Status}}' uptrust-gateway

⁠Backups

Make sure to back up the password encryption key, which is auto-generated when missing.

• /var/opt/uptrust/conf/private/pwenc (password encryption key, auto-generated when missing)
• /var/opt/uptrust/conf/private/pwd (admin login password hash, set on first launch)

Also back up the fallback email encryption key store files, which are auto-generated when needed

• /var/opt/uptrust/keystores/fallback-smime.p12
• /var/opt/uptrust/keystores/fallback-pgp.asc