Deployment

Deployment

MailAfrica Agent can be deployed using Docker, systemd, or run directly on a VPS.

Docker (Recommended)

Build and Run

git clone https://github.com/cameltech/MailAfrica-Agent.git
cd MailAfrica-Agent
 
# Create .env with your credentials
cp .env.example .env
nano .env
 
# Build and start
docker compose up -d --build

Docker Compose Configuration

The docker-compose.yml defines a single service:

services:
  agent:
    build: .
    ports:
      - "8097:8000"
    volumes:
      - agent-data:/app/data
    env_file:
      - .env
    restart: unless-stopped
  • Port 8097 maps to container port 8000
  • Named volume agent-data persists the SQLite database
  • env_file loads your .env credentials

Dockerfile

Multi-stage build:

  1. Builder stage — Python 3.11-slim, installs uv, copies dependency files, installs deps
  2. Runtime stage — Python 3.11-slim, copies installed deps and source code

This keeps the final image small and secure.

Managing the Container

# View logs
docker compose logs -f agent
 
# Restart
docker compose restart agent
 
# Stop
docker compose down
 
# Rebuild after code changes
docker compose up -d --build

systemd

For non-Docker deployments, use the provided systemd unit file.

Install

# Create service user
sudo useradd -r -s /bin/false mailafrica
 
# Clone the repo
sudo -u mailafrica git clone https://github.com/cameltech/MailAfrica-Agent.git /opt/mailafrica-agent
 
# Install dependencies
cd /opt/mailafrica-agent
sudo -u mailafrica uv sync
 
# Copy and edit environment
sudo -u mailafrica cp .env.example .env
sudo -u mailafrica nano .env
 
# Install systemd unit
sudo cp deploy/mailafrica-agent-webhook.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now mailafrica-agent-webhook

Unit File

The systemd unit (deploy/mailafrica-agent-webhook.service) includes:

  • Runs as mailafrica user
  • Loads .env via EnvironmentFile
  • Restarts on failure with 5s delay
  • Hardened with NoNewPrivileges, ProtectSystem=full

Managing the Service

# Status
sudo systemctl status mailafrica-agent-webhook
 
# Restart
sudo systemctl restart mailafrica-agent-webhook
 
# View logs
sudo journalctl -u mailafrica-agent-webhook -f

GitHub Actions CI/CD

The repo includes a GitHub Actions workflow (.github/workflows/deploy.yml) that:

  1. Triggers on push to main
  2. SSHes to the VPS using a deploy key
  3. Runs deploy.sh which:
    • Does git pull --ff-only
    • Rebuilds Docker Compose (or restarts systemd)

Setup

  1. Add a repository secret VPS_SSH_KEY with your private SSH key
  2. Add a repository secret VPS_HOST with your server address
  3. The workflow handles the rest on every push to main

VPS Provisioning

For a fresh Ubuntu VPS, run the provisioning script:

bash deploy/setup_vps.sh

This installs Docker, creates the mailafrica user, clones the repo, and sets up the service.

Production Checklist

  • Set strong, unique values for all API keys
  • Use HTTPS (reverse proxy with nginx/caddy)
  • Configure firewall to only allow ports 80/443
  • Set up log rotation
  • Monitor disk space (SQLite database grows with conversations)
  • Back up agent.db regularly
  • Set AGENT_WEBHOOK_SECRET to a secure random string

Reverse Proxy (nginx)

server {
    listen 443 ssl http2;
    server_name agent.mailafrica.online;
 
    ssl_certificate /etc/letsencrypt/live/agent.mailafrica.online/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/agent.mailafrica.online/privkey.pem;
 
    location / {
        proxy_pass http://127.0.0.1:8097;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Health Check

Verify the deployment is working:

curl https://agent.mailafrica.online/health
# {"status": "ok"}

Or use the MCP check command:

uv run mailafrica-agent check
ArchitectureAPI Reference