# devture/exim-relay architecture

> Architecture diagram of the GitHub repository devture/exim-relay, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/devture/exim-relay
- Repository: https://github.com/devture/exim-relay

## Overview

##### Project Type and Purpose
- This is a containerized mail relay built around Exim. Its purpose is to provide a lightweight, secure, and configurable mail relay container that can either directly relay mail to destination servers or forward mail through a smart host.
- The project builds on Alpine Linux and is designed to be run in a Docker environment—with additional support for Docker Compose and secrets in container orchestration platforms.

##### File Structure
- Top-Level Files and Directories:
- Dockerfile: Defines the image build process, combining Alpine with Exim and custom configuration.
- exim.conf: The main configuration file used by Exim for controlling mail routing and header modifications.
- Makefile and LICENSE: Typical utility and legal structure, not directly affecting runtime architecture.
- README.md: Provides usage examples for various configurations (default, smarthost, DKIM setups, etc.) and highlights the environment variables.
- .github Directory (including workflows & FUNDING.yml): Indicates continuous integration/continuous deployment (CI/CD) practices.
- This simple project does not split into frontend/backend; instead it focuses on configuring and running a mail relay service inside a container.

##### README for Additional Insights
- The README details various setup modes (default, smarthost, DKIM) and stresses the importance of environment variables for tailoring the container’s behavior.
- It also explains advanced configurations such as Docker Secrets for secure password management, which is crucial when diagramming how external configuration (e.g., environment variables) injects dependencies or security parameters into the container.
- The examples provided (Docker commands and Docker Compose sections) offer clear instructions to see how the container communicates with external clients (sending/receiving email) and with remote mail servers.

##### Main Components of the System
- Docker Container:
- Built from an Alpine Linux base image.
- Contains the Exim mail server configured via exim.conf.
- Runs as a non-root exim user (uid=100, gid=101) for enhanced security.
- Exim Mail Relay Service:
- Handles incoming emails (via mapped port 25 on host to container port 8025) and routes them either directly or through a smarthost.
- Applies custom configurations (e.g., header modifications like the removal of Received headers).
- Environment Variables and Configuration:
- HOSTNAME, SMARTHOST, SMTP_USERNAME, and SMTP_PASSWORD define the specifics of mail routing and authentication.
- Optional variables for DKIM, relay restrictions (RELAY_FROM_HOSTS, RELAY_TO_DOMAINS, etc.), and sender verification.
- External Integrations:
- Docker Compose for orchestrating container setups.
- Docker Secrets support for securely managing sensitive credentials.
- CI/CD integration via GitHub workflows (.github/workflows) indicates automated testing/build processes.

##### Relationships and Interactions Between Components
- The Docker container acts as the primary execution environment, with Exim as the core service.
- Environment variables (provided either at runtime or via Docker Compose/Secrets) dynamically configure Exim’s behavior.
- Ports are mapped from the host to the container (host port 25 → container port 8025) to allow external SMTP traffic.
- When a smart host is configured, the Exim service forwards outgoing mail through an external relay, establishing network interactions with remote mail servers.
- CI/CD pipelines in the .github directory ensure that builds, tests, and deployments are consistent and up-to-date.

##### Architectural Patterns and Design Principles
- Containerization: Encapsulates the mail relay into a portable, secure Docker image.
- Security Best Practices: Running as a non-root user and using Docker Secrets.
- Modularity & Configuration as Code: All key settings are passed in via environment variables, making the image easily configurable for different deployment scenarios.
- Minimalism: The project’s architecture is kept lean, focusing only on essential components (build file, config, and documentation).

## Diagram (Mermaid)

```mermaid
flowchart TD
    A("CI/CD Pipeline (GitHub Workflows)"):::ext
    B("Docker Build Process"):::build
    F("Runtime Env Variables"):::env
    G("Docker Compose"):::env
    H("Docker Secrets"):::env
    I("Remote Mail Servers/Internet"):::ext
    J("Documentation (README.md)"):::docs

    A -->|"initiates"| B
    B -->|"builds"| D

    F -->|"injects"| D
    G -->|"injects"| D
    H -->|"injects"| D

    subgraph "Docker Exim Relay Container"
        direction TB
        D("Exim Mail Relay Service"):::service
        E("exim.conf"):::config
        D -->|"uses"| E
    end

    D -->|"forwards"| I
    I -->|"responds"| D

    J -->|"guides"| F

    classDef ext fill:#bbf,stroke:#333,stroke-width:2px;
    classDef build fill:#acf,stroke:#333,stroke-width:2px;
    classDef env fill:#dfd,stroke:#333,stroke-width:2px;
    classDef service fill:#fbb,stroke:#333,stroke-width:2px;
    classDef config fill:#fea,stroke:#333,stroke-width:2px;
    classDef docs fill:#cfc,stroke:#333,stroke-width:2px;

    click B "https://github.com/devture/exim-relay/tree/main/Dockerfile"
    click E "https://github.com/devture/exim-relay/blob/main/exim.conf"
    click A "https://github.com/devture/exim-relay/tree/main/.github/workflows"
    click J "https://github.com/devture/exim-relay/blob/main/README.md"
```
