Web-SMTP Relay

Web-SMTP Relay is a simple Go application that receives email details via an HTTP POST request and relays the email through an SMTP server. It includes basic authentication and configurable settings.

Features

• Receive email details (subject, body, and destinations) via HTTP POST
• Basic authentication for secure access
• Configurable SMTP relay settings (default and per-user)
• Flexible configuration through YAML file, environment variables, and command-line flags
• Docker support with multi-architecture builds

Table of Contents

• Web-SMTP Relay
  • Features
  • Table of Contents
  • Installation
  • Configuration
    • config.yaml
    • Environment Variables
    • Command-line Flags
  • Usage
  • Docker
  • Helm Chart
    • Prerequisites
    • Installing the Chart
    • Customizing the Chart
      • Customizing values.yaml
      • Using command-line parameters
    • Configuration Options
    • Updating the Chart
    • Uninstalling the Chart
    • Note on Secrets
  • Tests
  • License
    • Key points of the AGPLv3
  • Contributing
  • Support

Installation

1. Clone the repository:

   git clone https://github.com/sctg-development/web-smtp-relay.git
   cd web-smtp-relay

2. Build the application:

   go build -o web-smtp

Configuration

The application can be configured using a YAML file, environment variables, and command-line flags.

config.yaml

users:
  admin: 
    password: $2a$10$XOPbrlUPQdwdJUpSrIF6X.LbE14qsMmKGhM1A8W9iqDuy0Bx8KzWq
  # can be generated with `htpasswd -nbB -C 12 user realpassword | awk -F: '{print $2}'`
  newuser: 
    password: $2a$10$XOPbrlUPQdwdJUpSrIF6X.LbE14qsMmKGhM1A8W9iqDuy0Bx8KzWq
    smtp:
      # per user smtp settings
      host: smtp.example.com
      port: 587
      username: your_username
      password: your_password

smtp:
  host: smtp.example.com
  port: 587
  username: your_username
  password: your_password

port: 8080

Environment Variables

• WEB_SMTP_CONFIG_FILE: Path to the configuration file
• WEB_SMTP_PORT: Port to listen on

Command-line Flags

• -c: Path to the configuration file
• -p: Port to listen on

Usage

1. Start the server:

   ./web-smtp

2. Send a POST request to http://localhost:8080/send with the following JSON body:

   {
     "subject": "Test Subject",
     "body": "This is a test email",
     "destinations": ["[email protected]"]
   }

   Include Basic Authentication headers with your request.

Docker

The project includes a Dockerfile and GitHub Actions workflow for building and pushing a multi-architecture Docker image.

To run the application using Docker:

docker run -p 8080:8080 -v /path/to/your/config.yaml:/app/config.yaml sctg/web-smtp-relay:latest

Helm Chart

This project includes a Helm chart for easy deployment to Kubernetes clusters. The chart creates a Deployment, Service, and ConfigMap for the Web-SMTP Relay application.

Prerequisites

• Kubernetes cluster
• Helm 3.x installed

Installing the Chart

1. If you don't want to install the chart you can use our public Helm repository:

helm repo add highcanfly <https://helm-repo.highcanfly.club/>
helm repo update highcanfly

Then install the chart:

helm upgrade --install --create-namespace --namespace web-smtp-relay web-smtp-relay highcanfly/web-smtp-relay --values values.yaml

2. Clone the repository or download the Helm chart files.

3. Navigate to the chart directory:

cd web-smtp-relay

4. Install the chart with the release name my-web-smtp-relay:

helm install my-web-smtp-relay .

Customizing the Chart

You can customize the chart by modifying the values.yaml file or by passing values on the command line.

Customizing values.yaml

Edit the values.yaml file to change default values. For example:

replicaCount: 2

image:
  repository: sctg/web-smtp-relay
  tag: "1.2.0"

config:
  users:
    admin: 
      password: $2y$12$2Rr0ZTQkfR08gxEDaT0DnukqKcITrjTnnV4cNwE23cEdMv1YSIHSK # admin123
      # generated with `htpasswd -nbB -C 12 user admin123 | awk -F: '{print $2}'`
      smtp:
        # per user smtp configuration
        host: smtp-for-admin.example.com
        port: 587
        username: your_username_specific_for_admin
        password: your_password_specific_for_admin
    user1:
      password: $2y$12$viL9Crn/J7PXuEEHsQOXmuJaVE9jCs1AJqBucL.EN9sAyLE1qkzB6 # user1123
      # generated with `htpasswd -nbB -C 12 user user1123
      # no smtp configuration for user1 so it will use the default smtp configuration

  smtp:
    # default smtp configuration
    host: smtp.example.com
    port: 587
    username: your_username
    password: your_password

  port: 8080
  
ingress:
  enabled: true
  host: web-smtp-relay.mycompany.com
  annotations: {}
  clusterIssuer: "cert-manager"

Using command-line parameters

You can override values when installing or upgrading the chart:

helm install my-web-smtp-relay . \
  --set replicaCount=3 \
  --set config.smtp.host=smtp.newhost.com \
  --set config.smtp.username=newuser \
  --set config.smtp.password=newpassword

Configuration Options

Parameter	Description	Default
replicaCount	Number of replicas for the deployment	1
image.repository	Docker image repository	yourdockerhubusername/web-smtp-relay
image.tag	Docker image tag	"latest"
image.pullPolicy	Image pull policy	IfNotPresent
service.type	Kubernetes service type	ClusterIP
service.port	Kubernetes service port	8080
config.users	Map of username to bcrypt hashed passwords	See values.yaml
config.smtp.host	SMTP server hostname	smtp.example.com
config.smtp.port	SMTP server port	587
config.smtp.username	SMTP username	your_username
config.smtp.password	SMTP password	your_password
config.port	Application listening port	8080
resources	CPU/Memory resource requests/limits	See values.yaml

Updating the Chart

To update the chart with new values:

helm upgrade my-web-smtp-relay . --reuse-values --set config.smtp.host=smtp.newhost.com

Uninstalling the Chart

To uninstall/delete the my-web-smtp-relay deployment:

helm uninstall my-web-smtp-relay

Note on Secrets

For production use, it's recommended to use Kubernetes Secrets for sensitive information like SMTP credentials and user passwords. You can create a secret separately and reference it in the Helm chart. This example uses ConfigMap for simplicity, but for real-world scenarios, consider using Secrets for better security.

Tests

To run tests, configure the config.yaml file, launch the server and use the following command:

DESTINATION="[email protected]" tests/external_tests.sh

or for a more realistic test:

SCHEME=https HOST=web-smtp-relay.example.com PORT=443 USER=myuser PASSWORD=user_password [email protected] tests/external_tests

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3).

Key points of the AGPLv3

1. Source Code: You must make the complete source code available when you distribute the software.
2. Modifications: If you modify the software, you must release your modifications under the AGPLv3 as well.
3. Network Use: If you run a modified version of the software on a server and allow users to interact with it over a network, you must make the source code of your modified version available.
4. No Additional Restrictions: You cannot impose any further restrictions on the recipients' exercise of the rights granted by the license.

For the full license text, see the LICENSE file in the project repository or visit GNU AGPL v3.0.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Support

If you encounter any problems or have any questions, please open an issue in the GitHub repository.