/manhquydev/email-platform

Wiki directory

Browse AI-generated documentation for any repository.

Quick Start with Docker

Relevant source files

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

This guide provides instructions for setting up and running the Email Platform using Docker and Docker Compose. The project is fully containerized, allowing for a consistent one-command deployment for both local development and production environments. This approach simplifies dependency management and ensures a reproducible setup across different machines.

The Docker configuration includes everything needed to run the full stack: the backend API, the frontend web application, databases, and various supporting services for email testing, monitoring, and reverse proxying. Separate compose files are provided to tailor the deployment for development versus production needs, with the production setup including automated HTTPS.

Sources: README.md:25-27, deployment_guide.md:46-48, blueprint.md:28-31

Architecture Overview

The application is composed of multiple services that are orchestrated by Docker Compose. There are two main configurations: a development setup for local work and a production setup optimized for deployment on a public server.

Development Environment

The development environment, defined in docker-compose.yml, is designed for local testing and includes services for email testing and monitoring.

This diagram shows the services included in the development Docker Compose setup.

Generating architecture diagram...

Sources: deployment_guide.md:49-56, README.md:25-27

Production Environment

The production environment uses docker-compose.prod.yml and adds a Caddy reverse proxy for automatic HTTPS via Let's Encrypt. It is configured to use a real domain and can be extended with optional anti-abuse services.

This diagram illustrates the production service architecture, including the Caddy reverse proxy.

Generating architecture diagram...

Sources: deployment_guide.md:60-63, deployment_guide.md:144-158, blueprint.md:28-31

Configuration

Environment variables are used to configure the services. You should copy the example .env files and customize them for your environment.

Key Environment Variables

For the API service (services/api/.env), the following variables are crucial:

Variable	Description	Example Value	Source File
`JWT_SECRET`	A strong secret key for signing JWT tokens.	`your-super-strong-secret`	`deployment_guide.md:37`
`DEFAULT_ADMIN_EMAIL`	The email for the default admin user created on first boot.	`admin@example.com`	`README.md:41`
`DEFAULT_ADMIN_PASSWORD`	The password for the default admin user.	`changeme`	`README.md:42`
`ALLOW_AUTO_DOMAIN_CREATION`	If `true`, allows creating domains automatically on email receipt. Set to `false` in production.	`false`	`README.md:36`
`OUTBOUND_ENABLED`	Set to `true` to enable sending outbound emails.	`true`	`deployment_guide.md:38`
`OUTBOUND_SMTP_HOST`	Hostname of the outbound SMTP relay (e.g., Mailpit for dev, SES for prod).	`mailpit` / `email-smtp.us-east-1.amazonaws.com`	`deployment_guide.md:40`
`OUTBOUND_SMTP_PORT`	Port for the outbound SMTP relay.	`1025` / `587`	`deployment_guide.md:41`
`WEB_URL`	The public URL of the web frontend.	`https://yourdomain.com`	`deployment_guide.md:46`

For the production setup, a root .env file is required to configure Caddy and other services:

Variable	Description	Example Value	Source File
`DOMAIN`	Your main domain name for which HTTPS will be configured.	`yourdomain.com`	`deployment_guide.md:67`
`ACME_EMAIL`	The email address used for Let's Encrypt registration.	`admin@yourdomain.com`	`deployment_guide.md:68`
`POSTGRES_PASSWORD`	A secure password for the PostgreSQL database.	`generated-secure-password`	`deployment_guide.md:69`

Sources: deployment_guide.md:34-48, deployment_guide.md:65-78, README.md:32-36

Getting Started

Follow these steps to run the application locally for development.

Initial Setup Flow

This sequence diagram outlines the process from cloning the repository to logging into the application.

Generating architecture diagram...

Sources: README.md:30-44, deployment_guide.md:47-48, services/api/package.json:10

Step-by-Step Commands

Clone the Repository

git clone https://github.com/manhquydev/email-platform.git
cd email-platform

Sources: deployment_guide.md:28-29

Configure the API
Copy the example environment file and update secrets as needed.
```
cd services/api
copy .env.example .env
# update JWT_SECRET, DEFAULT_ADMIN_* if needed
```
Sources: README.md:31-34
Build and Run Containers
From the root of the repository, start all services using Docker Compose.
```
docker compose up --build
```
This command will start the API on http://localhost:3001 and the SMTP server on localhost:2525.
Sources: README.md:38, deployment_guide.md:47
Apply Database Migrations
Once the containers are running, apply the database schema.
```
docker compose exec api npx prisma migrate deploy
```
Sources: README.md:40, services/api/package.json:10
Log In
The system seeds a default admin user on the first run. You can log in via the API or the web UI using the credentials from your .env file (DEFAULT_ADMIN_EMAIL and DEFAULT_ADMIN_PASSWORD).
Sources: README.md:42-44

Service Details

The table below describes the primary services defined in the Docker Compose files.

Service	Image/Build Context	Ports (Dev)	Description	Source
`api`	`services/api`	`3001:3001`, `2525:25`	The backend API (Fastify) and inbound SMTP server.	README.md:21, 39
`web`	`services/web`	`5173:5173`	The frontend web application (React + Vite).	README.md:23, 49
`postgres`	`postgres:16-alpine`	`5432:5432`	PostgreSQL database for storing all application data.	blueprint.md:162, TESTING_PLAN.md:32
`redis`	`redis:7-alpine`	`6379:6379`	Redis server used for caching and background job queues.	README.md:21, TESTING_PLAN.md:33
`mailpit`	`axllent/mailpit`	`8025:8025`, `1025:1025`	Email testing tool to catch outbound emails in development.	`deployment_guide.md:40-44`
`prometheus`	`prom/prometheus`	`9090:9090`	Monitoring system for collecting metrics from the API.	`deployment_guide.md:55`
`grafana`	`grafana/grafana`	`3000:3000`	Visualization tool for viewing Prometheus metrics.	`deployment_guide.md:55`
`caddy`	`caddy`	`80:80`, `443:443`	(Production only) Reverse proxy that provides automatic HTTPS.	`deployment_guide.md:62`

Production Deployment

For production, use the docker-compose.prod.yml file. This setup is designed for a server with a public IP and a configured domain name.

Create Root .env File: Create a .env file in the project root with your DOMAIN, ACME_EMAIL, and other production secrets.
Sources: deployment_guide.md:65-78
Build and Run: Use the -f flag to specify the production compose file.
```
docker-compose -f docker-compose.prod.yml up -d --build
```
Sources: deployment_guide.md:81
Automated Deployment: A deploy.sh script is provided to automate the production deployment process, which includes pulling the latest code, rebuilding containers, and running migrations.
```
./scripts/deploy.sh
```
Sources: scripts/deploy.sh

Summary

The Email Platform leverages Docker to provide a streamlined and consistent environment for both development and production. For local development, docker-compose.yml offers a comprehensive stack with tools for testing and monitoring. For production, docker-compose.prod.yml and the deploy.sh script provide a robust, secure, and automated deployment workflow, including automatic HTTPS. By following the steps in this guide, developers can quickly get the entire platform up and running.

Sources: README.md:25-27, deployment_guide.md:1-4

Quick Start with Docker

Relevant source files

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

Sources: README.md:25-27, deployment_guide.md:46-48, blueprint.md:28-31

Architecture Overview

Development Environment

The development environment, defined in docker-compose.yml, is designed for local testing and includes services for email testing and monitoring.

This diagram shows the services included in the development Docker Compose setup.

Generating architecture diagram...

Sources: deployment_guide.md:49-56, README.md:25-27

Production Environment

This diagram illustrates the production service architecture, including the Caddy reverse proxy.

Generating architecture diagram...

Sources: deployment_guide.md:60-63, deployment_guide.md:144-158, blueprint.md:28-31

Configuration

Environment variables are used to configure the services. You should copy the example .env files and customize them for your environment.

Key Environment Variables

For the API service (services/api/.env), the following variables are crucial:

Variable	Description	Example Value	Source File
`JWT_SECRET`	A strong secret key for signing JWT tokens.	`your-super-strong-secret`	`deployment_guide.md:37`
`DEFAULT_ADMIN_EMAIL`	The email for the default admin user created on first boot.	`admin@example.com`	`README.md:41`
`DEFAULT_ADMIN_PASSWORD`	The password for the default admin user.	`changeme`	`README.md:42`
`ALLOW_AUTO_DOMAIN_CREATION`	If `true`, allows creating domains automatically on email receipt. Set to `false` in production.	`false`	`README.md:36`
`OUTBOUND_ENABLED`	Set to `true` to enable sending outbound emails.	`true`	`deployment_guide.md:38`
`OUTBOUND_SMTP_HOST`	Hostname of the outbound SMTP relay (e.g., Mailpit for dev, SES for prod).	`mailpit` / `email-smtp.us-east-1.amazonaws.com`	`deployment_guide.md:40`
`OUTBOUND_SMTP_PORT`	Port for the outbound SMTP relay.	`1025` / `587`	`deployment_guide.md:41`
`WEB_URL`	The public URL of the web frontend.	`https://yourdomain.com`	`deployment_guide.md:46`

For the production setup, a root .env file is required to configure Caddy and other services:

Variable	Description	Example Value	Source File
`DOMAIN`	Your main domain name for which HTTPS will be configured.	`yourdomain.com`	`deployment_guide.md:67`
`ACME_EMAIL`	The email address used for Let's Encrypt registration.	`admin@yourdomain.com`	`deployment_guide.md:68`
`POSTGRES_PASSWORD`	A secure password for the PostgreSQL database.	`generated-secure-password`	`deployment_guide.md:69`

Sources: deployment_guide.md:34-48, deployment_guide.md:65-78, README.md:32-36

Getting Started

Follow these steps to run the application locally for development.

Initial Setup Flow

This sequence diagram outlines the process from cloning the repository to logging into the application.

Generating architecture diagram...

Sources: README.md:30-44, deployment_guide.md:47-48, services/api/package.json:10

Step-by-Step Commands

Clone the Repository

git clone https://github.com/manhquydev/email-platform.git
cd email-platform

Sources: deployment_guide.md:28-29

Configure the API
Copy the example environment file and update secrets as needed.
```
cd services/api
copy .env.example .env
# update JWT_SECRET, DEFAULT_ADMIN_* if needed
```
Sources: README.md:31-34
Build and Run Containers
From the root of the repository, start all services using Docker Compose.
```
docker compose up --build
```
This command will start the API on http://localhost:3001 and the SMTP server on localhost:2525.
Sources: README.md:38, deployment_guide.md:47
Apply Database Migrations
Once the containers are running, apply the database schema.
```
docker compose exec api npx prisma migrate deploy
```
Sources: README.md:40, services/api/package.json:10
Log In
The system seeds a default admin user on the first run. You can log in via the API or the web UI using the credentials from your .env file (DEFAULT_ADMIN_EMAIL and DEFAULT_ADMIN_PASSWORD).
Sources: README.md:42-44

Service Details

The table below describes the primary services defined in the Docker Compose files.

Service	Image/Build Context	Ports (Dev)	Description	Source
`api`	`services/api`	`3001:3001`, `2525:25`	The backend API (Fastify) and inbound SMTP server.	README.md:21, 39
`web`	`services/web`	`5173:5173`	The frontend web application (React + Vite).	README.md:23, 49
`postgres`	`postgres:16-alpine`	`5432:5432`	PostgreSQL database for storing all application data.	blueprint.md:162, TESTING_PLAN.md:32
`redis`	`redis:7-alpine`	`6379:6379`	Redis server used for caching and background job queues.	README.md:21, TESTING_PLAN.md:33
`mailpit`	`axllent/mailpit`	`8025:8025`, `1025:1025`	Email testing tool to catch outbound emails in development.	`deployment_guide.md:40-44`
`prometheus`	`prom/prometheus`	`9090:9090`	Monitoring system for collecting metrics from the API.	`deployment_guide.md:55`
`grafana`	`grafana/grafana`	`3000:3000`	Visualization tool for viewing Prometheus metrics.	`deployment_guide.md:55`
`caddy`	`caddy`	`80:80`, `443:443`	(Production only) Reverse proxy that provides automatic HTTPS.	`deployment_guide.md:62`

Production Deployment

For production, use the docker-compose.prod.yml file. This setup is designed for a server with a public IP and a configured domain name.

Create Root .env File: Create a .env file in the project root with your DOMAIN, ACME_EMAIL, and other production secrets.
Sources: deployment_guide.md:65-78
Build and Run: Use the -f flag to specify the production compose file.
```
docker-compose -f docker-compose.prod.yml up -d --build
```
Sources: deployment_guide.md:81
Automated Deployment: A deploy.sh script is provided to automate the production deployment process, which includes pulling the latest code, rebuilding containers, and running migrations.
```
./scripts/deploy.sh
```
Sources: scripts/deploy.sh

Summary

Sources: README.md:25-27, deployment_guide.md:1-4