Papercut-SMTP/docker-compose.example.yml at develop · ChangemakerStudios/Papercut-SMTP · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
# Docker Compose example for Papercut SMTP Service
# Copy this file to docker-compose.yml and customize as needed

services:
  papercut-smtp:
    image: changemakerstudiosus/papercut-smtp:latest
    container_name: papercut-smtp
    ports:
      # Web UI
      - "8080:8080"
      # SMTP (plain - default)
      - "2525:2525"
    volumes:
      # Persist email messages
      - papercut-data:/app/Incoming
      # Persist logs
      - papercut-logs:/app/Logs
    environment:
      # Basic SMTP configuration
      - SmtpServer__IP=Any
      - SmtpServer__Port=2525
      # IP Allowlist for SMTP connections (optional)
      # Use "*" to allow all IPs (default), or specify CIDR ranges
      # Examples:
      # - SmtpServer__AllowedIps=192.168.1.0/24,10.0.0.0/8  # Allow specific networks
      # - SmtpServer__AllowedIps=192.168.1.100,192.168.1.101  # Allow specific IPs
      - SmtpServer__AllowedIps=*
    restart: unless-stopped

  # Example: Papercut with TLS/STARTTLS support
  papercut-smtp-tls:
    image: changemakerstudiosus/papercut-smtp:latest
    container_name: papercut-smtp-tls
    profiles:
      - tls  # Enable with: docker-compose --profile tls up
    ports:
      - "8080:8080"
      - "587:587"  # STARTTLS port
    volumes:
      - papercut-data-tls:/app/Incoming
      - papercut-logs-tls:/app/Logs
      # Mount certificate directory (adjust path to your cert location)
      # - /path/to/certs:/certs:ro
    environment:
      - SmtpServer__IP=Any
      - SmtpServer__Port=587
      - SmtpServer__AllowedIps=*
      # TLS/STARTTLS Configuration
      # Uncomment and configure these to enable TLS
      # Simple approach - use certificate by name (most common):
      - SmtpServer__CertificateFindType=FindBySubjectName
      - SmtpServer__CertificateFindValue=localhost
      # - SmtpServer__CertificateStoreLocation=LocalMachine
      # - SmtpServer__CertificateStoreName=My
      #
      # Alternative - use thumbprint (more specific but harder to use):
      # - SmtpServer__CertificateFindType=FindByThumbprint
      # - SmtpServer__CertificateFindValue=YOUR_CERT_THUMBPRINT_HERE
    restart: unless-stopped

  # Example: Multiple ports (plain SMTP + STARTTLS)
  # Note: This requires running multiple instances or modifying the service
  # to support multiple endpoints (future enhancement)

volumes:
  papercut-data:
    driver: local
  papercut-logs:
    driver: local
  papercut-data-tls:
    driver: local
  papercut-logs-tls:
    driver: local

# Usage:
# 1. Basic (plain SMTP):
#    docker-compose up -d papercut-smtp
#
# 2. With TLS (requires certificate configuration):
#    docker-compose --profile tls up -d
#
# 3. View logs:
#    docker-compose logs -f papercut-smtp
#
# 4. Stop:
#    docker-compose down

# TLS Certificate Setup for Docker:
#
# Option 1: Use host certificate store (Windows only)
#   - Install certificate on host machine
#   - Configure CertificateFindType and CertificateFindValue
#   - Container will access host's certificate store
#
# Option 2: Mount certificate file (cross-platform)
#   - Generate or obtain a PFX certificate
#   - Mount certificate directory to container
#   - Use CertificateFindType=FindBySubjectName
#   - Ensure certificate is in container's cert store
#
# Option 3: Self-signed certificate (development)
#   On Windows host:
#   $cert = New-SelfSignedCertificate -Subject "CN=localhost" `
#       -DnsName "localhost" -CertStoreLocation "cert:\LocalMachine\My" `
#       -NotAfter (Get-Date).AddYears(2)
#   $cert.Thumbprint  # Use in CertificateFindValue

# Testing TLS:
#   openssl s_client -connect localhost:587 -starttls smtp
#   # Should show STARTTLS in EHLO response

# IP Allowlist Configuration:
#
# The SmtpServer__AllowedIps environment variable controls which IP addresses
# can connect to the SMTP server. This provides additional security.
#
# Syntax:
#   - SmtpServer__AllowedIps=*                           # Allow all IPs (default)
#   - SmtpServer__AllowedIps=192.168.1.0/24              # Allow single CIDR range
#   - SmtpServer__AllowedIps=192.168.1.0/24,10.0.0.0/8   # Allow multiple CIDR ranges
#   - SmtpServer__AllowedIps=192.168.1.100               # Allow single IP
#   - SmtpServer__AllowedIps=192.168.1.100,192.168.1.101 # Allow multiple IPs
#
# Notes:
#   - Applies only to SMTP connections, not HTTP web UI access
#   - Localhost (127.0.0.1/::1) is always allowed for SMTP
#   - IPv4 and IPv6 are both supported
#   - CIDR notation allows efficient network range specification
#   - Changes require container restart