# Deployment & Docker

# Deployment & Docker

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [emailsender/.env.example](emailsender/.env.example)
- [emailsender/Dockerfile](emailsender/Dockerfile)

</details>



This page details the containerization strategy and deployment requirements for the **EmailSender** microservice. The service uses a multi-stage Docker build process to optimize image size and security, ensuring that only necessary production dependencies and compiled artifacts are included in the final runtime environment.

## Docker Build Pipeline

The `emailsender` microservice utilizes a two-stage `Dockerfile` based on the `node:22-alpine` image. This approach separates the build-time environment (which requires TypeScript and development dependencies) from the runtime environment.

### 1. Builder Stage
The first stage, labeled `builder`, is responsible for compiling the TypeScript source code into executable JavaScript.
*   **Base Image**: `node:22-alpine` [emailsender/Dockerfile:1]()
*   **Dependency Management**: Installs `pnpm` globally and runs `pnpm install --frozen-lockfile` to ensure deterministic builds [emailsender/Dockerfile:9-12]().
*   **Compilation**: Executes `pnpm run build` to generate the `dist/` directory [emailsender/Dockerfile:18]().

### 2. Production Stage
The second stage creates the final image used for deployment.
*   **Selective Copying**: It only copies `package.json`, `pnpm-lock.yaml`, and the compiled `dist/` folder from the `builder` stage [emailsender/Dockerfile:29-35]().
*   **Production Dependencies**: Runs `pnpm install --prod` to exclude `devDependencies`, reducing the attack surface and image footprint [emailsender/Dockerfile:32]().
*   **Runtime Command**: The container starts by executing `node dist/index.js` [emailsender/Dockerfile:48]().

### Docker Build Flow
The following diagram illustrates the transition from source code to a production-ready container.

**Diagram: Multi-Stage Build Process**
```mermaid
graph TD
    subgraph "Stage 1: Builder"
        A["Source Code (.ts)"] --> B["pnpm install (All)"]
        B --> C["pnpm run build"]
        C --> D["/app/dist (JS)"]
    end

    subgraph "Stage 2: Production"
        D --> E["Copy /dist"]
        F["package.json"] --> G["pnpm install --prod"]
        E --> H["Final Image"]
        G --> H
    end

    H --> I["CMD node dist/index.js"]
```
**Sources:** [emailsender/Dockerfile:1-48]()

## Environment Configuration

The microservice requires several environment variables to function correctly. These are defined in the `.env.example` file and must be provided at runtime (e.g., via a `.env` file or container orchestration platform).

| Variable | Description | Example Value |
| :--- | :--- | :--- |
| `DATABASE_URL` | PostgreSQL connection string | `postgresql://user:pass@host:5432/db` |
| `DB_SCHEMA` | The specific schema for this microservice | `emailsender` |
| `NATS_URL` | Connection string for the NATS messaging server | `nats://127.0.0.1:4222` |
| `BREVO_API_KEY` | API key for the Brevo email provider | `your_brevo_api_key_here` |
| `BREVO_API_ENDPOINT` | Brevo API base URL | `https://api.brevo.com/v1` |
| `SERVICE_CODE` | Identifier for the service registry | `EMAILSENDER` |
| `SERVICE_BASE_URL` | The URL where this service is reachable | `http://localhost:3003` |
| `WEBHOOK_API_KEY` | Key used to authorize incoming webhooks | `your_webhook_api_key_here` |

**Sources:** [emailsender/.env.example:1-8]()

## Health Monitoring

The `Dockerfile` includes a `HEALTHCHECK` directive to allow the container orchestrator (e.g., Docker Compose, Kubernetes) to monitor the service's status.

*   **Mechanism**: It executes a Node.js snippet that performs an HTTP GET request to the internal `/health` endpoint [emailsender/Dockerfile:44-45]().
*   **Parameters**:
    *   `interval`: 30 seconds.
    *   `timeout`: 10 seconds.
    *   `start-period`: 5 seconds (allows the service time to initialize before checks begin).
    *   `retries`: 3.
*   **Success Condition**: The service must return a `200 OK` status code; otherwise, the container is marked as unhealthy [emailsender/Dockerfile:45]().

**Sources:** [emailsender/Dockerfile:44-45]()

## Build and Run Instructions

To build and run the container locally, use the following commands from the `emailsender` directory:

### Build the Image
```bash
docker build -t primebrick-emailsender .
```

### Run the Container
The container exposes port `3003` [emailsender/Dockerfile:41](). When running, you must map this port and provide the necessary environment variables.

```bash
docker run -d \
  --name emailsender-service \
  -p 3003:3003 \
  --env-file .env \
  primebrick-emailsender
```

### Service-Code Mapping
The following diagram maps the Docker configuration to the internal service components.

**Diagram: Container to Code Entity Mapping**
```mermaid
graph LR
    subgraph "Docker Container"
        EX["EXPOSE 3003"]
        HC["HEALTHCHECK"]
        CMD["CMD node dist/index.js"]
    end

    subgraph "Code Entities"
        SVR["HttpServer (src/index.ts)"]
        H_END["/health (src/index.ts)"]
        ENTRY["index.ts"]
    end

    EX --> SVR
    HC -- "Polls" --> H_END
    CMD -- "Starts" --> ENTRY
```
**Sources:** [emailsender/Dockerfile:41-48]()

---