Copy page

Microservices

Deployment & Docker

Deployment & Docker

Relevant source files

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

• emailsender/.env.example
• emailsender/Dockerfile

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

Code
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

Code
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.

Code
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

Code
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

---