docker-compose.yml

name: emailengine

# IMPORTANT: EmailEngine is resource-intensive
# - Minimum: 8GB RAM, 4 CPU cores for production
# - Recommended: 16GB+ RAM, 8+ CPU cores
# - See DOCKER_DEPLOYMENT.md for deployment guidance

services:
    emailengine:
        restart: ${RESTART_POLICY:-unless-stopped}
        image: postalsys/emailengine:${EMAILENGINE_VERSION:-latest}
        ports:
            # API and web interface
            - '${EMAILENGINE_API_BIND:-127.0.0.1}:${EMAILENGINE_API_PORT:-3000}:3000'
            # SMTP for message submission
            - '${EMAILENGINE_SMTP_BIND:-127.0.0.1}:${EMAILENGINE_SMTP_PORT:-2525}:2525'
            # IMAP proxy
            - '${EMAILENGINE_IMAP_BIND:-127.0.0.1}:${EMAILENGINE_IMAP_PORT:-9993}:9993'
        depends_on:
            redis:
                condition: ${REDIS_HEALTHCHECK:-service_healthy}
        networks:
            - emailengine-network
        environment:
            # Configuration via environment variables
            # For the full list see https://learn.emailengine.app/docs/configuration

            # Settings to write to v1/settings on startup
            EENGINE_SETTINGS: ${EENGINE_SETTINGS:-}

            # Encryption secret for stored credentials - REQUIRED. Generate one with
            # `openssl rand -hex 32` and put it in .env; compose refuses to start without it,
            # since a default here would encrypt every account password with a public key
            EENGINE_SECRET: '${EENGINE_SECRET:?EENGINE_SECRET must be set in .env - generate one with openssl rand -hex 32}'

            # Database connection URL
            EENGINE_REDIS: ${EENGINE_REDIS:-redis://redis:6379/2}

            # The image trusts X-Forwarded-For (EENGINE_API_PROXY=true) so the client address
            # comes from your reverse proxy. Name the proxy here (IPs or CIDRs, comma-separated,
            # e.g. the Docker bridge gateway or the proxy container's address), otherwise any
            # client that reaches the port directly can pick its own source address and the
            # admin IP allowlist and per-token address restrictions cannot be relied on
            EENGINE_API_PROXY_ADDRESSES: ${EENGINE_API_PROXY_ADDRESSES:-}

            # Additional settings
            EENGINE_LOG_LEVEL: ${EENGINE_LOG_LEVEL:-info}
            EENGINE_WORKERS: ${EENGINE_WORKERS:-4}

        healthcheck:
            # 127.0.0.1 and not localhost: the image is Alpine, so this is BusyBox wget on musl.
            # musl returns ::1 first for localhost (both are in the container's /etc/hosts) and
            # BusyBox wget connects to that one address without falling back to the next, while
            # EmailEngine listens on 0.0.0.0, which is IPv4 only. Through localhost the check can
            # only ever report "connection refused", so the container stays unhealthy for good and
            # anything chained behind `depends_on: service_healthy` waits forever.
            test: ['CMD', 'wget', '--no-verbose', '--tries=1', '--spider', 'http://127.0.0.1:3000/health']
            interval: ${HEALTHCHECK_INTERVAL:-30s}
            timeout: ${HEALTHCHECK_TIMEOUT:-10s}
            retries: ${HEALTHCHECK_RETRIES:-3}
            start_period: ${HEALTHCHECK_START_PERIOD:-40s}
        logging:
            driver: 'json-file'
            options:
                max-size: '${LOG_MAX_SIZE:-100m}'
                max-file: '${LOG_MAX_FILE:-10}'
                compress: '${LOG_COMPRESS:-true}'

    redis:
        # IMPORTANT: Redis is used as a DATABASE, not a cache
        # - No memory limits are set (uses available system memory)
        # - Eviction policy is 'noeviction' to prevent data loss
        # - Monitor memory usage: docker-compose exec redis redis-cli INFO memory
        image: redis:${REDIS_VERSION:-7-alpine}
        restart: ${RESTART_POLICY:-unless-stopped}
        networks:
            - emailengine-network
        command: >
            sh -c "
            if [ -n \"$$REDIS_PASSWORD\" ]; then
                exec redis-server \
                    --requirepass \"$$REDIS_PASSWORD\" \
                    --maxmemory-policy noeviction \
                    --tcp-backlog 511 \
                    --tcp-keepalive 300 \
                    --timeout 0 \
                    --databases 16 \
                    --loglevel ${REDIS_LOG_LEVEL:-notice} \
                    --save 900 1 \
                    --save 300 10 \
                    --save 60 10000 \
                    --stop-writes-on-bgsave-error yes \
                    --rdbcompression yes \
                    --rdbchecksum yes
            else
                exec redis-server \
                    --maxmemory-policy noeviction
            fi
            "
        environment:
            REDIS_PASSWORD: ${REDIS_PASSWORD:-}
            REDIS_LOG_LEVEL: ${REDIS_LOG_LEVEL:-notice}
        volumes:
            - redis-data:/data
        healthcheck:
            test: >
                sh -c "
                if [ -n \"$$REDIS_PASSWORD\" ]; then
                    REDISCLI_AUTH=\"$$REDIS_PASSWORD\" redis-cli --no-auth-warning ping
                else
                    redis-cli ping
                fi
                "
            interval: 10s
            timeout: 5s
            retries: 5
            start_period: 30s
        logging:
            driver: 'json-file'
            options:
                max-size: '50m'
                max-file: '5'
                compress: '${LOG_COMPRESS:-true}'

networks:
    emailengine-network:
        driver: bridge

volumes:
    redis-data:
        driver: local