Skip to content

About

Mailpit de SmartPot con SMTP autenticado y bandeja protegida

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

SmartPot-Mail (Mailpit)

Mail Image CI Publish Docker Images

English | Español


English

Overview

SmartPot-Mail is the SmartPot mail server, powered by Mailpit. It receives the emails sent by SmartPot-API — welcome and password recovery — and displays them in a protected web UI. When an SMTP relay is configured, it also forwards them to a real SMTP provider so they reach users' inboxes.

Port Purpose Production
1025 Authenticated SMTP Internal Docker network only
8025 Mailpit web UI and API, protected by username & pass https://mail.smartpot.app behind Nginx
flowchart LR
  api["SmartPot-API"]
  subgraph mail["SmartPot-Mail Container · axllent/mailpit:v1.33.0"]
    direction TB
    entry["entrypoint.sh<br/>Configures SMTP auth & UI auth"]
    smtp["SMTP Server :1025<br/>Plain Auth No-Enc on internal network"]
    web["Web UI :8025<br/>Protected mailbox view"]
    health["Healthcheck<br/>/mailpit readyz"]
  end
  api -->|"welcome & reset emails"| smtp
  entry --> smtp & web
Loading

Security

  • SMTP requires a username and password (MAIL_USERNAME, MAIL_PASSWORD); plain authentication without TLS is only allowed because traffic never leaves the internal network.
  • The web UI requires its own username and password (MAILPIT_UI_USERNAME, MAILPIT_UI_PASSWORD).
  • Credentials are passed to Mailpit via environment variables: they are never written to files or printed in logs.
  • Runs as user 1000 with a read-only filesystem; messages live in /tmp and expire after 30 days or once 500 messages are exceeded.

Project Structure

SmartPot-Mail/
├── .github/
│   ├── dependabot.yml
│   └── workflows/
│       ├── ci.yml              # Builds the image and runs the security smoke test
│       ├── packaging.yml       # Publishes the image to GHCR with SBOM and provenance (and Docker Hub when configured)
│       └── deploy.yml          # Triggers deployment on the central SmartPotTech/.github workflow
├── tests/
│   └── smoke.sh                # SMTP and UI authentication, delivery, and secret-free logs
├── compose.yaml
├── Dockerfile                  # Unprivileged axllent/mailpit
├── entrypoint.sh               # Translates credentials into Mailpit environment variables
└── .env.example

Installation Guide

One-Command Deployment

The image is public: ghcr.io/smartpottech/smartpot-mail. The full platform, including this service, starts with a single command without cloning the code:

curl -fsSL https://raw.githubusercontent.com/SmartPotTech/.github/main/docker/demo/compose.yaml | docker compose -f - up -d --wait

Open http://localhost:5173 and sign in with demo@smartpot.app / SmartPot2026. Stop it with docker compose -p smartpot-demo down (add -v to also remove data). See the demo for details.

To run only this service from the published image:

docker run -d --name smartpot-mail --read-only --tmpfs /tmp --cap-drop ALL \
  -p 127.0.0.1:1025:1025 -p 127.0.0.1:8025:8025 \
  -e MAIL_USERNAME=smartpot -e MAIL_PASSWORD=<smtp-password> \
  -e MAILPIT_UI_USERNAME=admin -e MAILPIT_UI_PASSWORD=<ui-password> \
  ghcr.io/smartpottech/smartpot-mail:latest

From Source with Docker Compose

cp .env.example .env    # set both passwords
docker compose up -d

Open http://localhost:8025 with the UI credentials. The API connects with:

MAIL_HOST=localhost  MAIL_PORT=1025  MAIL_USERNAME=smartpot  MAIL_PASSWORD=<MAIL_PASSWORD>  MAIL_SMTP_AUTH=true

Real Delivery (Optional)

Mailpit can forward all messages to an upstream SMTP provider. Uncomment the MP_SMTP_RELAY_* variables in .env.example with the provider details (e.g., a Gmail app password) and set MP_SMTP_RELAY_ALL=true.

Smoke Test

docker build -t smartpot-mail:ci .
sh tests/smoke.sh smartpot-mail:ci

The test starts a throwaway container and verifies the public health endpoint, the 401 on the web API without credentials, the SMTP rejection of anonymous or wrongly authenticated mail, the delivery of an authenticated message, and its subject, recipient and body through the Mailpit API. It then deletes only its own messages. Docker, curl and Python 3 are required; swaks is used when available and Python smtplib otherwise. SMTP_HOST, SMTP_PORT, SMTP_AUTH (LOGIN/PLAIN), SMTP_USER, SMTP_PASSWORD, SMTP_FROM, SMTP_TO, MAILPIT_API_URL, MAILPIT_UI_USERNAME, MAILPIT_UI_PASSWORD and PYTHON can be overridden; SMOKE_EXTERNAL=1 targets an already running server instead of creating the container.

Published Image

docker pull ghcr.io/smartpottech/smartpot-mail:latest

Every change on main runs through CI, publishes the image to GHCR (and Docker Hub as a replica when credentials are present), and triggers the central deployment workflow in SmartPotTech/.github, which updates production one service at a time and checks /health.

Documentation

Email covers welcome and password recovery; crop alerts go through the PWA and Telegram. Component documentation is in docs/ (also in DOCX and PDF), with diagrams in docs/diagrams.

License

This project is licensed under the MIT License. See LICENSE for details.


Español

Descripción

SmartPot-Mail es el servidor de correo de SmartPot, basado en Mailpit. Recibe los correos que envía SmartPot-API —bienvenida y recuperación de contraseña— y los muestra en una interfaz web protegida. Si se configura un relay, además los reenvía a un SMTP real para que lleguen a los usuarios.

Puerto Uso Producción
1025 SMTP con autenticación Solo la red interna de Docker
8025 Interfaz web y API de Mailpit, con usuario y contraseña https://mail.smartpot.app a través de Nginx
flowchart LR
  api["SmartPot-API"]
  subgraph mail["SmartPot-Mail Container · axllent/mailpit:v1.33.0"]
    direction TB
    entry["entrypoint.sh<br/>Configures SMTP auth & UI auth"]
    smtp["SMTP Server :1025<br/>Plain Auth No-Enc on internal network"]
    web["Web UI :8025<br/>Protected mailbox view"]
    health["Healthcheck<br/>/mailpit readyz"]
  end
  api -->|"welcome & reset emails"| smtp
  entry --> smtp & web
Loading

Seguridad

  • SMTP exige usuario y contraseña (MAIL_USERNAME, MAIL_PASSWORD); la autenticación sin TLS solo se permite porque el tráfico no sale de la red interna.
  • La interfaz web exige su propio usuario y contraseña (MAILPIT_UI_USERNAME, MAILPIT_UI_PASSWORD). Antes era pública.
  • Las credenciales se pasan a Mailpit por variables de entorno: no se escriben en archivos ni aparecen en los logs.
  • Corre como el usuario 1000, con sistema de archivos de solo lectura; los mensajes viven en /tmp y se descartan a los 30 días o al superar 500.

Estructura del Proyecto

SmartPot-Mail/
├── .github/
│   ├── dependabot.yml
│   └── workflows/
│       ├── ci.yml              # Construye la imagen y corre la prueba de seguridad
│       ├── packaging.yml       # Publica la imagen en GHCR con SBOM y procedencia (y en Docker Hub con credenciales)
│       └── deploy.yml          # Pide el despliegue al workflow central de SmartPotTech/.github
├── tests/
│   └── smoke.sh                # Autenticación SMTP e interfaz, entrega y logs sin secretos
├── compose.yaml
├── Dockerfile                  # axllent/mailpit sin privilegios
├── entrypoint.sh               # Traduce las credenciales a la configuración de Mailpit
└── .env.example

Guía de Instalación

Despliegue en un comando

La imagen es pública: ghcr.io/smartpottech/smartpot-mail. La plataforma completa, con este servicio incluido, se levanta con un solo comando y sin descargar el código:

curl -fsSL https://raw.githubusercontent.com/SmartPotTech/.github/main/docker/demo/compose.yaml | docker compose -f - up -d --wait

Abre http://localhost:5173 e ingresa con demo@smartpot.app / SmartPot2026. Se detiene con docker compose -p smartpot-demo down (con -v borra también los datos). Más detalle en la demo.

Solo este servicio, con la imagen publicada:

docker run -d --name smartpot-mail --read-only --tmpfs /tmp --cap-drop ALL \
  -p 127.0.0.1:1025:1025 -p 127.0.0.1:8025:8025 \
  -e MAIL_USERNAME=smartpot -e MAIL_PASSWORD=<contraseña-smtp> \
  -e MAILPIT_UI_USERNAME=admin -e MAILPIT_UI_PASSWORD=<contraseña-de-la-interfaz> \
  ghcr.io/smartpottech/smartpot-mail:latest

Desde el código con Docker Compose

cp .env.example .env    # define las dos contraseñas
docker compose up -d

Abre http://localhost:8025 con el usuario de la interfaz. La API se conecta con:

MAIL_HOST=localhost  MAIL_PORT=1025  MAIL_USERNAME=smartpot  MAIL_PASSWORD=<MAIL_PASSWORD>  MAIL_SMTP_AUTH=true

Entrega real (opcional)

Mailpit puede reenviar todos los mensajes a un proveedor SMTP. Descomenta las variables MP_SMTP_RELAY_* del .env.example con los datos del proveedor (por ejemplo, una contraseña de aplicación de Gmail) y deja MP_SMTP_RELAY_ALL=true.

Prueba de humo

docker build -t smartpot-mail:ci .
sh tests/smoke.sh smartpot-mail:ci

La prueba arranca un contenedor desechable y verifica el endpoint público de salud, el 401 de la API web sin credenciales, el rechazo SMTP del correo anónimo o con clave incorrecta, la entrega de un mensaje autenticado y su asunto, destinatario y cuerpo a través de la API de Mailpit. Después borra solo sus propios mensajes. Requiere Docker, curl y Python 3; usa swaks si está disponible y, si no, smtplib de Python. Se pueden sobrescribir SMTP_HOST, SMTP_PORT, SMTP_AUTH (LOGIN/PLAIN), SMTP_USER, SMTP_PASSWORD, SMTP_FROM, SMTP_TO, MAILPIT_API_URL, MAILPIT_UI_USERNAME, MAILPIT_UI_PASSWORD y PYTHON; SMOKE_EXTERNAL=1 apunta a un servidor ya arrancado en lugar de crear el contenedor.

Imagen publicada

docker pull ghcr.io/smartpottech/smartpot-mail:latest

Cada cambio en main pasa por el CI, publica la imagen en GHCR (y en Docker Hub como réplica cuando el repositorio tiene credenciales) y pide el despliegue al workflow central de SmartPotTech/.github, que actualiza producción de a uno y verifica /health.

Documentación

El correo cubre la bienvenida y la recuperación de la contraseña; los avisos del cultivo van por la PWA y Telegram. Su documentación propia está en docs/ (también en DOCX y PDF), con sus diagramas en docs/diagrams.

Licencia

Este proyecto está bajo la licencia MIT. Consulta el archivo LICENSE para más detalles.

About

Mailpit de SmartPot con SMTP autenticado y bandeja protegida

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages