PostMTA
menu_bookDocumentation

Everything You Need to Deploy & Operate

From quick start to production hardening — comprehensive guides for deploying, configuring, and managing your PostMTA platform. Built on KumoMTA.

Quick StartAPI ReferenceDeployment GuideProduction HardeningTesting
code

API Reference

Complete endpoint reference with examples

rocket_launch

Deployment Guide

Step-by-step installation instructions

shield

Production Hardening

Security checklist and best practices

science

Testing

Comprehensive test suite reference

visibility

Request Demo

See PostMTA in action

Get Started in Under 30 Minutes

Deploy PostMTA on Ubuntu 24.04 using the interactive deployment script — zero manual configuration needed.

One-Click Deployment

sudo bash deployment/interactive-deploy.sh

The script will prompt you for your domain, database credentials, JWT secret, and other configuration options. It auto-detects and installs missing dependencies, builds binaries, sets up systemd services, and runs health checks.

System Requirements

ComponentMinimumRecommended
CPU4 vCPU8 vCPU
RAM8 GB16 GB
Disk100 GB SSD500 GB SSD
OSUbuntu 22.04 / 24.04Ubuntu 24.04 LTS
PostgreSQL14+16
Redis6+7

LLM Auto-Healing

During deployment, you can optionally enable LLM-powered auto-healing powered by Qwen2.5-Coder-0.5B. When a step fails, the local model analyzes the error and generates a fix command. After successful deployment, the LLM removes itself — no trace left on the server.

How it works:

  1. Step fails → LLM receives error context and the command that failed
  2. LLM generates a bash fix command
  3. Script applies the fix and retries the step
  4. If fix works → deployment continues normally
  5. If fix fails → falls back to standard retry logic

Manual Deployment Guide

Step-by-step manual installation for full control over the deployment process.

1. Install Dependencies
sudo apt-get update && sudo apt-get install -y curl wget git build-essential postgresql postgresql-contrib redis-server nginx ufw certbot python3-certbot-nginx fail2ban unzip
2. Install Go 1.22+
wget https://go.dev/dl/go1.22.12.linux-amd64.tar.gz
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.22.12.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc
3. Install Node.js 20 LTS
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt-get install -y nodejs
4. Clone & Setup
git clone <repo-url> /opt/postmta
cd /opt/postmta
sudo useradd --system --user-group --create-home --home-dir /opt/postmta postmta || true
sudo mkdir -p /opt/postmta/{api,dashboard,config,logs,scripts,master-agent,tls}
5. Configure Environment
# Generate a secure JWT secret
JWT_SECRET=$(openssl rand -base64 32)

# Edit /opt/postmta/.env with your values:
# DATABASE_URL, REDIS_URL, JWT_SECRET, CORS_ALLOWED_ORIGINS, KUMOMTA_ENDPOINT
6. PostgreSQL Setup
sudo systemctl enable postgresql && sudo systemctl start postgresql
sudo -u postgres psql -c "CREATE USER postmta WITH PASSWORD 'your_password';"
sudo -u postgres psql -c "CREATE DATABASE postmta OWNER postmta;"
PGPASSWORD='your_password' psql -h localhost -U postmta -d postmta -f database/schema.sql
7. Build API
cd /opt/postmta/api
go build -o postmta-api -ldflags='-s -w' .
8. Build Dashboard
cd /opt/postmta/dashboard
npm install
npm run build
9. Build Master Agent
cd /opt/postmta/master-agent
go build -o postmta-agent -ldflags='-s -w' .
10. Setup systemd Services
sudo systemctl daemon-reload
sudo systemctl enable postmta-api postmta-dashboard postmta-master-agent
sudo systemctl start postmta-api
sudo systemctl start postmta-dashboard
sudo systemctl start postmta-master-agent

Security Checklist

Configuration recommendations and security hardening steps for production deployments.

Production Hardening Checklist

JWT secretChange from default: openssl rand -base64 32
CORS restrictionSet CORS_ALLOWED_ORIGINS to your domain
TLS enabledLet's Encrypt via certbot
Database passwordChange from default, use strong password
Redis passwordSet requirepass in redis.conf
Rate limiter active600 req/min per user, wired to all routes
Firewall configuredOnly ports 22, 80, 443, 587, 465 open
fail2ban installedProtects against brute force attacks
PostgreSQL not publiclisten_addresses = 'localhost'
Redis not publicbind 127.0.0.1
Auto-healing systemdRestart=on-failure configured
Log rotation30-day retention configured
Regular backupspg_dump cron job scheduled
Production endpoint configuredPoint KUMOMTA_ENDPOINT to real MTA server
Dashboard behind NginxNot exposed directly to the internet

Comprehensive Test Suite

Extensive test coverage across all API endpoints, failover scenarios, and load testing at scale.

Deep Regression(112 tests)

bash tests/deep-regression.sh http://localhost:8080

Failover Tests(16 tests)

bash tests/failover_test.sh

Full Suite(All phases)

bash tests/run-all.sh

Go Integration(5 tests)

cd api && go test ./tests/... -v

Load Test (100K)(100K messages)

bash tests/load/load_test_100k.sh 50 100000

Smoke Tests(Per-endpoint)

bash tests/smoke/api_health.sh

Ready to Deploy PostMTA?

Get started with the interactive deployment script or reach out for enterprise support and a personalized demo.

supportContact SalesvisibilityRequest Demo