# postalserver/install architecture

> Architecture diagram of the GitHub repository postalserver/install, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/postalserver/install
- Repository: https://github.com/postalserver/install

## Overview

This repository is not the Postal application itself; it is the installation and bootstrap layer used to provision Postal environments.

1. **Primary purpose**
   - The repo packages the scripts, config examples, and Docker Compose templates needed to get Postal running quickly.
   - It supports two deployment generations side by side: **Postal v2** and **Postal v3**.

2. **Main entrypoint**
   - `bin/postal` is the likely user-facing installer/bootstrap command.
   - It is the natural starting point for orchestration: a user runs the command, which then prepares prerequisites and deployment configuration.

3. **Prerequisite installation subsystem**
   - `prerequisites/install-ubuntu.v2.sh` and `prerequisites/install-ubuntu.v3.sh` are environment-prep scripts for Ubuntu.
   - Their job is to install required system dependencies and supporting services before Postal itself is deployed.
   - The README explicitly notes these scripts may install databases with insecure defaults, so they are intended for quick starts and testing, not production-hardening.

4. **Deployment template subsystem**
   - `templates/docker-compose.v2.yml` and `templates/docker-compose.v3.yml` define the container topology for each Postal version.
   - This is the core infrastructure definition in the repo: services, container relationships, and runtime wiring are encoded here.
   - The split by version suggests the runtime stack differs between Postal releases, so the templates are version-specific rather than one-size-fits-all.

5. **Example configuration subsystem**
   - `examples/postal.v2.yml` and `examples/postal.v3.yml` provide sample Postal application configuration for each version.
   - `examples/Caddyfile` provides reverse-proxy/web-server configuration, indicating Postal is commonly fronted by Caddy in this setup.
   - These files are reference inputs for generating or validating a working installation.

6. **Versioned architecture boundary**
   - The repository cleanly separates v2 and v3 artifacts instead of abstracting them into one unified format.
   - That means version choice affects both prerequisite installation and deployment composition, not just application settings.

7. **Runtime shape implied by the artifacts**
   - The installation flow likely results in a host running support services plus a containerized Postal stack.
   - Docker Compose is the main runtime boundary; Caddy sits at the edge as the ingress/reverse proxy, while Postal services run behind it.

8. **Data/config flow**
   - User invokes the installer or curl-based prerequisite scripts.
   - Host prerequisites are installed.
   - Version-specific compose and config examples are used to assemble the Postal environment.
   - Caddy and Postal configs provide the final service wiring for runtime startup.

9. **Operational scope**
   - This repo focuses on provisioning and bootstrapping, not on business logic, queues, mail processing, or APIs.
   - Any actual Postal runtime behavior lives outside this repository; here you only see how it is deployed and initialized.

10. **Relevant external dependencies**
   - Ubuntu is the documented OS target for the provided prerequisite scripts.
   - Docker Compose is the main deployment mechanism.
   - Caddy is used as the edge proxy in the example setup.
   - Database services are part of the prerequisite/install story, but the repo intentionally keeps that setup simple for convenience.

11. **How to draw the architecture**
   - Put the user at the top interacting with `bin/postal` or the shell install scripts.
   - Show a provisioning layer that installs OS dependencies and supporting services.
   - Show a versioned configuration layer feeding Docker Compose.
   - Show Caddy at the edge, with Postal containers behind it.
   - Treat the repo itself as an installer/configuration package, not as the application runtime.

Main entry points: [`bin/postal`](https://github.com/postalserver/install/tree/main/bin/postal) (postal), [`prerequisites/install-ubuntu.v2.sh`](https://github.com/postalserver/install/blob/main/prerequisites/install-ubuntu.v2.sh) (Ubuntu v2), [`prerequisites/install-ubuntu.v3.sh`](https://github.com/postalserver/install/blob/main/prerequisites/install-ubuntu.v3.sh) (Ubuntu v3), [`templates/docker-compose.v2.yml`](https://github.com/postalserver/install/blob/main/templates/docker-compose.v2.yml) (Compose v2)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Bootstrap"]
  node_installer["postal<br/>installer"]
  node_ubuntu_v2["Ubuntu v2<br/>provisioning script"]
  node_ubuntu_v3["Ubuntu v3<br/>provisioning script"]
  node_prereqs[("Host deps<br/>os prerequisites")]
  node_db_setup[("Database setup<br/>support service")]
end

subgraph group_v2["Postal v2"]
  node_compose_v2["Compose v2<br/>deployment template"]
  node_config_v2["Config v2<br/>example config<br/>[postal.v2.yml]"]
  node_stack_v2[("Postal v2 stack<br/>runtime stack")]
end

subgraph group_v3["Postal v3"]
  node_compose_v3["Compose v3<br/>deployment template"]
  node_config_v3["Config v3<br/>example config<br/>[postal.v3.yml]"]
  node_stack_v3[("Postal v3 stack<br/>runtime stack")]
end

subgraph group_edge["Edge"]
  node_caddyfile["Caddyfile<br/>edge config"]
  node_caddy{{"Caddy edge<br/>reverse proxy"}}
end

node_user(("User<br/>actor"))
node_repo["Install repo<br/>bootstrap package"]

node_user -->|"run"| node_installer
node_user -.->|"install v2"| node_ubuntu_v2
node_user -.->|"install v3"| node_ubuntu_v3
node_installer -->|"prepare"| node_prereqs
node_installer -->|"assemble v2"| node_compose_v2
node_installer -->|"assemble v3"| node_compose_v3
node_installer -->|"load v2"| node_config_v2
node_installer -->|"load v3"| node_config_v3
node_ubuntu_v2 -->|"install"| node_prereqs
node_ubuntu_v3 -->|"install"| node_prereqs
node_ubuntu_v2 -.->|"include"| node_db_setup
node_ubuntu_v3 -.->|"include"| node_db_setup
node_compose_v2 -->|"define"| node_stack_v2
node_compose_v3 -->|"define"| node_stack_v3
node_config_v2 -->|"configure"| node_stack_v2
node_config_v3 -->|"configure"| node_stack_v3
node_caddyfile -->|"configure"| node_caddy
node_caddy -->|"fronts"| node_stack_v2
node_caddy -->|"fronts"| node_stack_v3
node_repo -->|"contains"| node_installer
node_repo -->|"contains"| node_compose_v2
node_repo -->|"contains"| node_compose_v3
node_repo -->|"contains"| node_caddyfile

click node_installer "https://github.com/postalserver/install/tree/main/bin/postal"
click node_ubuntu_v2 "https://github.com/postalserver/install/blob/main/prerequisites/install-ubuntu.v2.sh"
click node_ubuntu_v3 "https://github.com/postalserver/install/blob/main/prerequisites/install-ubuntu.v3.sh"
click node_compose_v2 "https://github.com/postalserver/install/blob/main/templates/docker-compose.v2.yml"
click node_config_v2 "https://github.com/postalserver/install/blob/main/examples/postal.v2.yml"
click node_compose_v3 "https://github.com/postalserver/install/blob/main/templates/docker-compose.v3.yml"
click node_config_v3 "https://github.com/postalserver/install/blob/main/examples/postal.v3.yml"
click node_caddyfile "https://github.com/postalserver/install/tree/main/examples/Caddyfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_installer,node_ubuntu_v2,node_ubuntu_v3,node_prereqs,node_db_setup toneBlue
class node_compose_v2,node_config_v2,node_stack_v2 toneAmber
class node_compose_v3,node_config_v3,node_stack_v3 toneMint
class node_caddyfile,node_caddy toneRose
class node_user,node_repo toneNeutral
```

## Components

### Bootstrap

Installer entrypoint and host provisioning scripts.

- [postal](https://github.com/postalserver/install/tree/main/bin/postal): installer · Main bootstrap command for provisioning a Postal environment. · `bin/postal`
- [Ubuntu v2](https://github.com/postalserver/install/blob/main/prerequisites/install-ubuntu.v2.sh): provisioning script · Installs host prerequisites for Postal v2. · `prerequisites/install-ubuntu.v2.sh`
- [Ubuntu v3](https://github.com/postalserver/install/blob/main/prerequisites/install-ubuntu.v3.sh): provisioning script · Installs host prerequisites for Postal v3. · `prerequisites/install-ubuntu.v3.sh`
- **Host deps**: os prerequisites · Ubuntu packages and supporting services installed before Postal runs.
- **Database setup**: support service · Convenience database installation performed by the prerequisite scripts.

### Postal v2

Version 2 deployment artifacts.

- [Compose v2](https://github.com/postalserver/install/blob/main/templates/docker-compose.v2.yml): deployment template · Docker Compose topology for Postal v2. · `templates/docker-compose.v2.yml`
- [Config v2](https://github.com/postalserver/install/blob/main/examples/postal.v2.yml): example config · Sample Postal configuration for v2. · `examples/postal.v2.yml`
- **Postal v2 stack**: runtime stack · Containerized Postal v2 services and wiring.

### Postal v3

Version 3 deployment artifacts.

- [Compose v3](https://github.com/postalserver/install/blob/main/templates/docker-compose.v3.yml): deployment template · Docker Compose topology for Postal v3. · `templates/docker-compose.v3.yml`
- [Config v3](https://github.com/postalserver/install/blob/main/examples/postal.v3.yml): example config · Sample Postal configuration for v3. · `examples/postal.v3.yml`
- **Postal v3 stack**: runtime stack · Containerized Postal v3 services and wiring.

### Edge

Ingress and reverse-proxy configuration.

- [Caddyfile](https://github.com/postalserver/install/tree/main/examples/Caddyfile): edge config · Example reverse-proxy configuration for Caddy. · `examples/Caddyfile`
- **Caddy edge**: reverse proxy · Ingress layer that fronts the Postal runtime.

### Other components

- **User**: actor · Runs the installer and selects a Postal version.
- **Install repo**: bootstrap package · Repository packaging scripts, templates, and example configuration.

## Connections

- User → postal: run · Start provisioning from the main bootstrap command.
- User → Ubuntu v2: install v2 · Alternative direct prerequisite path for Postal v2.
- User → Ubuntu v3: install v3 · Alternative direct prerequisite path for Postal v3.
- postal → Host deps: prepare · Installs host dependencies before runtime deployment.
- postal → Compose v2: assemble v2 · Uses the v2 deployment template when provisioning Postal v2.
- postal → Compose v3: assemble v3 · Uses the v3 deployment template when provisioning Postal v3.
- postal → Config v2: load v2 · Consumes sample v2 configuration as input for setup.
- postal → Config v3: load v3 · Consumes sample v3 configuration as input for setup.
- Ubuntu v2 → Host deps: install · Provision v2 host dependencies and supporting services.
- Ubuntu v3 → Host deps: install · Provision v3 host dependencies and supporting services.
- Ubuntu v2 → Database setup: include · May install database services with convenience defaults.
- Ubuntu v3 → Database setup: include · May install database services with convenience defaults.
- Compose v2 → Postal v2 stack: define · Describes the v2 container topology.
- Compose v3 → Postal v3 stack: define · Describes the v3 container topology.
- Config v2 → Postal v2 stack: configure · Provides application settings for the v2 stack.
- Config v3 → Postal v3 stack: configure · Provides application settings for the v3 stack.
- Caddyfile → Caddy edge: configure · Defines the edge proxy behavior.
- Caddy edge → Postal v2 stack: fronts · Routes traffic to the Postal v2 runtime.
- Caddy edge → Postal v3 stack: fronts · Routes traffic to the Postal v3 runtime.
- Install repo → postal: contains · Repository packages the bootstrap entrypoint.
- Install repo → Compose v2: contains · Repository includes the v2 deployment template.
- Install repo → Compose v3: contains · Repository includes the v3 deployment template.
- Install repo → Caddyfile: contains · Repository includes the example edge configuration.
