Raspberry Pi Mail Server Build: Stalwart Docker & Hardware Watchdog

Running a self-hosted email server on a Raspberry Pi is a rite of passage for homelab builders, but it is notoriously fragile. A hung Docker container or a locked-up I/O bus on a microSD card will silently drop your incoming mail for days. To build a reliable raspberry pi mail server in 2026, you need more than just software; you need hardware-level telemetry and an automated recovery circuit.

This guide walks through deploying the modern, Rust-based Stalwart Mail Server via Docker on a Raspberry Pi 5, paired with an I2C OLED status dashboard and a GPIO-driven hardware watchdog relay that physically power-cycles the board if the mail daemon stops responding.

Hardware Spec Sheet & Parts List

Before flashing an OS, gather the exact hardware. The Raspberry Pi 5’s RP1 southbridge chip handles I2C and GPIO differently than the Pi 4, making component selection critical for stable 24/7 operation.

Pin Mapping & Wiring the Hardware Watchdog

The watchdog circuit uses a relay to momentarily short the Argon ONE case’s power button pins, simulating a physical press to force a reboot if the software stack locks up. The OLED uses the primary I2C bus.

Wiring the Relay to the Argon Case: Locate the two pins on the Argon ONE V3 PCB labeled for the external power button. Solder two jumper wires to these pads and connect them to the relay’s COM (Common) and NO (Normally Open) terminals. When GPIO 17 pulls low, the relay closes the circuit, triggering the case's hardware reset logic.

Deploying Stalwart Mail Server via Docker

Stalwart has largely replaced Postfix/Dovecot stacks for homelabs due to its single-binary Rust architecture, JMAP support, and lower memory footprint. We run it via Docker Compose to isolate the network stack.

1. Install Docker and enable I2C: sudo apt install docker.io docker-compose i2c-tools
2. Add your user to the docker and i2c groups: sudo usermod -aG docker,i2c $USER (then reboot).
3. Create your project directory: mkdir ~/stalwart-mail && cd ~/stalwart-mail
4. Create docker-compose.yml mapping ports 25 (SMTP), 143 (IMAP), and 8080 (Web Admin).
5. Pull and start the container: docker compose up -d

Python Status Monitor & Watchdog Code

This Python script polls the Stalwart local API, renders stats to the SSD1306 OLED, and triggers the GPIO 17 relay if the API fails to respond for three consecutive cycles. This targets the Raspberry Pi 5 (4GB) running Raspberry Pi OS (Bookworm or later) using the gpiozero and luma.oled libraries.

import time
import requests
from gpiozero import OutputDevice
from luma.core.interface.serial import i2c
from luma.oled.device import ssd1306
from PIL import ImageFont, ImageDraw, Image
import subprocess

# --- PIN & HARDWARE DEFINITIONS ---
WATCHDOG_RELAY_PIN = 17  # BCM GPIO 17
I2C_PORT = 1
OLED_ADDRESS = 0x3C
STALWART_API_URL = "http://127.0.0.1:8080/api/v1/status"
API_TIMEOUT = 5.0  # seconds
MAX_FAILURES = 3

# Initialize Hardware
relay = OutputDevice(WATCHDOG_RELAY_PIN, active_high=False) # Low-level trigger
serial = i2c(port=I2C_PORT, address=OLED_ADDRESS)
device = ssd1306(serial, width=128, height=64)

# Font setup (use default if custom ttf is missing)
try:
    font = ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", 12)
except IOError:
    font = ImageFont.load_default()

fail_count = 0

def get_cpu_temp():
    try:
        output = subprocess.check_output(["vcgencmd", "measure_temp"]).decode()
        return output.replace("temp=", "").replace("'C\n", "C")
    except Exception:
        return "N/A"

def trigger_watchdog_reset():
    print("CRITICAL: Stalwart unresponsive. Triggering hardware reset.")
    relay.on()  # Closes NO circuit, simulating power button press
    time.sleep(2)
    relay.off()

def main():
    global fail_count
    relay.off() # Ensure relay is open (normal state)
    
    while True:
        image = Image.new("1", (device.width, device.height))
        draw = ImageDraw.Draw(image)
        
        # Poll Stalwart API
        try:
            response = requests.get(STALWART_API_URL, timeout=API_TIMEOUT)
            if response.status_code == 200:
                status = "ONLINE"
                fail_count = 0
            else:
                status = f"HTTP {response.status_code}"
                fail_count += 1
        except requests.exceptions.RequestException as e:
            status = "TIMEOUT"
            fail_count += 1
            
        # Render to OLED
        draw.text((0, 0), f"Mail: {status}", font=font, fill=255)
        draw.text((0, 16), f"Temp: {get_cpu_temp()}", font=font, fill=255)
        draw.text((0, 32), f"Fails: {fail_count}/{MAX_FAILURES}", font=font, fill=255)
        
        device.display(image)
        
        # Watchdog Logic
        if fail_count >= MAX_FAILURES:
            trigger_watchdog_reset()
            fail_count = 0 # Reset counter post-trigger
            time.sleep(60) # Wait for Pi to reboot
            
        time.sleep(10) # 10 second poll interval

if __name__ == "__main__":
    try:
        main()
    except KeyboardInterrupt:
        relay.off()
        device.cleanup()
        print("Monitor stopped safely.")

Debugging: Connection Refused & Daemon Hangs

When integrating network daemons with hardware watchdogs, you will encounter specific failure modes. Here are the exact error strings and how to resolve them.

Error: Port Allocation Failure

Exact Error String: docker: Error response from daemon: driver failed programming external connectivity on endpoint stalwart-mailserver: Bind for 0.0.0.0:25 failed: port is already allocated.

Ranked Causes:

1. Pre-installed MTA: Raspberry Pi OS often includes Exim4 or Postfix by default, which grabs port 25 on boot.
2. Orphaned Container: A previous crashed Docker container still holds the network namespace.

Fix: Purge the host MTA with sudo apt purge exim4 postfix, then restart the Docker daemon: sudo systemctl restart docker.

Error: Python API Timeout

Exact Error String: ConnectionError: HTTPConnectionPool(host='127.0.0.1', port=8080): Max retries exceeded with url: /api/v1/status (Caused by NewConnectionError...)

Ranked Causes:

1. Docker Network Bridge Drop: The Pi's docker0 bridge interface dropped due to a kernel OOM (Out of Memory) event killing the Stalwart container.
2. I2C Bus Lockup: The RP1 chip’s I2C clock stretching bug caused the Python script to hang before it could even send the HTTP request.

The First Three Things to Check When It Fails

If your OLED goes blank or the watchdog starts rebooting the Pi in a loop, run these three diagnostics immediately via SSH:

1. Check Port Conflicts: Run sudo ss -tulpn | grep :25. If you see anything other than docker-proxy, a rogue host process is blocking the mail server.
2. Verify the API Directly: Run curl -v http://127.0.0.1:8080/api/v1/status. If this times out, Stalwart is dead, not the Python script.
3. Scan the I2C Bus: Run i2cdetect -y 1. If the grid is empty or shows UU, your Dupont wires are loose, or the OLED has suffered a voltage brownout and locked its internal controller. Power cycle the OLED VCC.

Extending or Simplifying the Build

Not every deployment needs a hardware watchdog or a Pi 5. Here is how to adapt this architecture to your specific constraints.

How to Simplify (Low Power / Low Budget)

If you are deploying this at a remote cabin on a solar battery system, drop the OLED and the Argon case. Use a Raspberry Pi Zero 2 W and disable the ClamAV antivirus module in Stalwart’s configuration file. ClamAV requires over 1GB of RAM just to load its signature database; disabling it allows the mail server to run comfortably on the Zero 2 W’s 512MB RAM. Rely on Docker's native restart: always policy instead of a hardware relay to handle software crashes.

How to Extend (High Volume / Production)

If you are hosting mail for multiple domains and high traffic, the microSD card I/O will become your primary bottleneck. Extend the build by adding the Geekworm X1001 PCIe to NVMe HAT and a 256GB M.2 2230 SSD. Move the entire /var/lib/docker directory to the NVMe drive. This reduces mail queue write latency from ~45ms (microSD) to < 1ms (NVMe), completely eliminating the I/O lockups that trigger false-positive watchdog reboots. Ensure you update your Pi 5 EEPROM to the latest 2026 release to enable PCIe Gen 3.0 speeds for the HAT.

Building a resilient raspberry pi mail server is less about the software configuration and more about anticipating the physical and network failures that inevitably occur in a homelab environment. By combining Stalwart's efficient Rust engine with a hardware-level watchdog, you ensure your inbox stays online, even when the OS doesn't.