Skip to content
Klutch.sh Docs

Deploying an AnonAddy App

Introduction

AnonAddy (now branded as addy.io) is a powerful open-source anonymous email forwarding service. It allows you to create unlimited aliases that forward to your real email address, protecting your privacy and helping you identify who sells your data. Key features include:

  • Unlimited email aliases – create aliases on-the-fly using your username subdomain or custom domains
  • GPG/OpenPGP encryption – encrypt forwarded emails with your public key
  • Reply anonymously – respond from aliases without revealing your real address
  • Custom domains – use your own domains for professional-looking aliases
  • Browser extensions & mobile apps – generate aliases from anywhere

Built with Laravel (PHP 8.2+), MySQL/MariaDB, Redis, and Postfix, AnonAddy is ideal for privacy-conscious users who want full control over their email forwarding infrastructure.

Deploying AnonAddy on Klutch.sh gives you automated builds from GitHub, managed secrets, persistent storage for DKIM keys and user data, plus the flexibility to configure SMTP relay for outbound email delivery.

Architecture overview

AnonAddy requires several components working together:

ComponentPurposeKlutch.sh deployment
Laravel app (PHP 8.2+)Web UI and APIMain HTTP app on port 8000
MySQL/MariaDBUser accounts, aliases, domainsSeparate TCP app or external database
RedisQueues and rate limitingSeparate TCP app or external service
PostfixInbound/outbound SMTPBuilt into the official Docker image
Rspamd (optional)Spam filtering and DKIM signingBuilt into the official Docker image

The official AnonAddy Docker image bundles the Laravel app, Postfix, and optional Rspamd into a single container, exposing:

  • Port 8000 – HTTP (web interface)
  • Port 25 – SMTP (mail server)
  • Port 11334 – Rspamd web dashboard (optional)

Important: AnonAddy requires port 25 for receiving and sending email. Many cloud providers block this port. You may need to request port 25 to be unblocked or use an SMTP relay service for outbound mail.

Prerequisites

Before deploying AnonAddy on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub repository (fork of the official AnonAddy Docker repo or your own with a Dockerfile)
  • A domain name you control with access to DNS settings
  • A MySQL/MariaDB database (deploy on Klutch.sh or use a managed service)
  • A Redis instance (deploy on Klutch.sh or use a managed service)
  • Basic understanding of DNS records (MX, SPF, DKIM, DMARC)
  • (Optional) An SMTP relay service (SendGrid, Mailgun, Amazon SES) for reliable outbound delivery

Deployment steps

  1. Prepare your GitHub repository

    Fork or clone the official AnonAddy Docker repository:

    Terminal window
    git clone https://github.com/anonaddy/docker.git anonaddy-docker
    cd anonaddy-docker
    git remote set-url origin https://github.com/YOUR_USERNAME/anonaddy-docker.git
    git push -u origin master

    The repository already contains a production-ready Dockerfile. Klutch.sh automatically detects the Dockerfile in the repository root and uses it for building—no manual selection is required.

    Alternatively, create a minimal Dockerfile that references the official image:

    FROM anonaddy/anonaddy:latest
    

    # The official image handles everything
    # Just ensure environment variables are configured in Klutch.sh

  2. Deploy MySQL on Klutch.sh (or use external database)

    AnonAddy requires MySQL or MariaDB for storing user accounts, aliases, and domain configurations.

    Option A: Deploy MySQL on Klutch.sh

    1. In klutch.sh/app, create a new app for MySQL.
    2. Connect a GitHub repository with a MySQL Dockerfile:
    FROM mysql:8
    

    ENV MYSQL_DATABASE=anonaddy
    ENV MYSQL_USER=anonaddy
    ENV MYSQL_PASSWORD=your-secure-password
    ENV MYSQL_ROOT_PASSWORD=your-root-password
    

    EXPOSE 3306
    1. Select TCP traffic and set the internal port to 3306.
    2. Attach a persistent volume with mount path /var/lib/mysql and size 20 GB.
    3. Deploy the app. Connect to it at your-mysql-app.klutch.sh:8000.

    Option B: Use a managed MySQL service

    Use a managed database like PlanetScale, Amazon RDS, or Google Cloud SQL. Note the connection details for environment variable configuration.

  3. Deploy Redis on Klutch.sh (or use external service)

    Redis is used for queues and rate limiting.

    1. Create a new app for Redis in klutch.sh/app.
    2. Use a simple Redis Dockerfile:
    FROM redis:7-alpine
    

    EXPOSE 6379
    

    CMD ["redis-server", "--appendonly", "yes"]
    1. Select TCP traffic and set the internal port to 6379.
    2. Optionally attach a persistent volume at /data with size 5 GB for AOF persistence.
    3. Deploy the app. Connect at your-redis-app.klutch.sh:8000.

  4. Create the AnonAddy app on Klutch.sh

    1. Log in to klutch.sh/app.
    2. Create a new project (if needed) by clicking New Project.
    3. Inside your project, click New App.
    4. Connect your GitHub repository containing the AnonAddy Dockerfile.
    5. Klutch.sh will detect the Dockerfile automatically and begin building.

  5. Configure environment variables

    In the Klutch.sh dashboard, navigate to your AnonAddy app’s Settings → Environment Variables. Add the following variables, marking sensitive values as secrets.

    Required variables:

    Terminal window
    # Timezone
    TZ=UTC
    

    # User/Group IDs (match your container setup)
    PUID=1000
    PGID=1000
    

    # Application
    APP_KEY=base64:YOUR_GENERATED_APP_KEY
    APP_URL=https://example-app.klutch.sh
    APP_DEBUG=false
    

    # AnonAddy specific
    ANONADDY_DOMAIN=example.com
    ANONADDY_HOSTNAME=mail.example.com
    ANONADDY_SECRET=your-long-random-secret-string
    

    # Database (adjust based on your MySQL deployment)
    DB_HOST=your-mysql-app.klutch.sh
    DB_PORT=8000
    DB_DATABASE=anonaddy
    DB_USERNAME=anonaddy
    DB_PASSWORD=your-database-password
    

    # Redis (adjust based on your Redis deployment)
    REDIS_HOST=your-redis-app.klutch.sh
    REDIS_PORT=8000
    

    # Mail configuration
    MAIL_FROM_NAME=AnonAddy
    MAIL_FROM_ADDRESS=addy@example.com

    Generate APP_KEY:

    Run this command locally to generate a Laravel app key:

    Terminal window
    echo "base64:$(openssl rand -base64 32)"

    Optional variables:

    Terminal window
    # Admin user (receives emails at root domain)
    ANONADDY_ADMIN_USERNAME=admin
    

    # Registration control
    ANONADDY_ENABLE_REGISTRATION=true
    

    # Additional domains (comma-separated)
    ANONADDY_ALL_DOMAINS=example.com,mail.example.com
    

    # Limits
    ANONADDY_LIMIT=200
    ANONADDY_BANDWIDTH_LIMIT=104857600
    ANONADDY_NEW_ALIAS_LIMIT=10
    ANONADDY_ADDITIONAL_USERNAME_LIMIT=10
    

    # Postfix relay (for outbound email via SMTP relay)
    POSTFIX_RELAYHOST=[smtp.sendgrid.net]:587
    POSTFIX_RELAYHOST_AUTH_ENABLE=true
    POSTFIX_RELAYHOST_USERNAME=apikey
    POSTFIX_RELAYHOST_PASSWORD=your-sendgrid-api-key
    POSTFIX_SMTP_TLS=encrypt
    

    # Rspamd (enable for DKIM signing and spam filtering)
    RSPAMD_ENABLE=true
    

    # DKIM
    ANONADDY_DKIM_SELECTOR=default

  6. Configure the internal port

    In your AnonAddy app’s settings:

    1. Select HTTP traffic for the web interface.
    2. Set the internal port to 8000.

    Note on SMTP: The official AnonAddy Docker image also exposes port 25 for SMTP. Klutch.sh HTTP routing handles the web interface, but for full email functionality you may need to configure an SMTP relay for outbound mail or work with your provider regarding port 25 access for inbound mail.

  7. Attach persistent storage

    AnonAddy requires persistent storage for DKIM keys, GnuPG keys, and application data.

    1. Navigate to Storage in your app’s settings.
    2. Click Add Volume.
    3. Configure:
      • Mount path: /data
      • Size: 20 GB (adjust based on expected usage)
    4. Save the volume.

    The /data directory stores:

    • DKIM private/public keys (/data/dkim/)
    • GnuPG keys for email signing (/data/.gnupg/)
    • Application storage and logs

  8. Deploy the application

    1. Push any final changes to your GitHub repository.
    2. In the Klutch.sh dashboard, click Deploy (or trigger a redeploy).
    3. Monitor the build logs for any errors.
    4. Once complete, your AnonAddy instance will be available at https://example-app.klutch.sh.

  9. Configure DNS records

    For AnonAddy to receive email, configure the following DNS records for your domain:

    MX Record:

    Type: MX
    Host: @
    Value: mail.example.com (or your Klutch.sh app hostname)
    Priority: 10

    SPF Record:

    Type: TXT
    Host: @
    Value: v=spf1 mx -all

    DKIM Record:

    After deployment, generate DKIM keys using the container’s built-in command (via Klutch.sh console):

    Terminal window
    gen-dkim

    This creates /data/dkim/example.com.private and /data/dkim/example.com.txt. Add the contents of the .txt file as a DNS TXT record:

    Type: TXT
    Host: default._domainkey
    Value: v=DKIM1; k=rsa; p=YOUR_PUBLIC_KEY...

    DMARC Record:

    Type: TXT
    Host: _dmarc
    Value: v=DMARC1; p=quarantine; adkim=s; aspf=s;

  10. Create your first user

    Use the Klutch.sh console to create an admin user:

    Terminal window
    anonaddy anonaddy:create-user "yourusername" "your-email@example.com"

    Follow the prompts to set a password. You can then log in at https://example-app.klutch.sh.

  11. Verify the deployment

    1. Open https://example-app.klutch.sh in your browser.
    2. Log in with the user you created.
    3. Create a test alias.
    4. Send an email to the alias and verify it forwards correctly.
    5. Test replying from an alias to confirm outbound email works.

Environment variables reference

VariableDefaultDescription
TZUTCContainer timezone
PUID / PGID1000User/group IDs for file permissions
APP_KEY—Laravel encryption key (required)
APP_URL—Public URL of your installation
ANONADDY_DOMAIN—Primary domain for email aliases (required)
ANONADDY_HOSTNAME—FQDN for the mail server
ANONADDY_SECRET—Secret for hashing anonymous reply data (required)
ANONADDY_ADMIN_USERNAME—Username that receives emails at root domain
ANONADDY_ENABLE_REGISTRATIONtrueAllow new user registrations
DB_HOST—MySQL hostname (required)
DB_PORT3306MySQL port
DB_DATABASEanonaddyDatabase name
DB_USERNAMEanonaddyDatabase user
DB_PASSWORD—Database password
REDIS_HOST—Redis hostname
REDIS_PORT6379Redis port
POSTFIX_RELAYHOST—SMTP relay server (e.g., [smtp.sendgrid.net]:587)
RSPAMD_ENABLEfalseEnable Rspamd for DKIM signing and spam filtering

Persistent storage paths

Mount pathPurposeRecommended size
/dataDKIM keys, GnuPG keys, app storage20 GB
/var/lib/mysql (MySQL app)Database files20–50 GB
/data (Redis app)AOF persistence5 GB

Sample Dockerfile

If you want to customize the official image, here’s a reference Dockerfile:

FROM anonaddy/anonaddy:latest


# The base image includes:
# - PHP 8.2 with required extensions
# - Nginx
# - Postfix mail server
# - Rspamd (optional spam filtering)
# - s6-overlay process supervisor


# Environment variables are configured via Klutch.sh dashboard
# Data is persisted to /data volume


# Ports exposed:
# - 8000: HTTP (web interface)
# - 25: SMTP (mail server)
# - 11334: Rspamd dashboard


# No additional configuration needed for basic deployments

Using an SMTP relay for outbound email

Many cloud environments block port 25. To ensure reliable outbound email delivery, configure an SMTP relay service:

SendGrid:

Terminal window
POSTFIX_RELAYHOST=[smtp.sendgrid.net]:587
POSTFIX_RELAYHOST_AUTH_ENABLE=true
POSTFIX_RELAYHOST_USERNAME=apikey
POSTFIX_RELAYHOST_PASSWORD=SG.your-sendgrid-api-key
POSTFIX_SMTP_TLS=encrypt

Mailgun:

Terminal window
POSTFIX_RELAYHOST=[smtp.mailgun.org]:587
POSTFIX_RELAYHOST_AUTH_ENABLE=true
POSTFIX_RELAYHOST_USERNAME=postmaster@your-domain.mailgun.org
POSTFIX_RELAYHOST_PASSWORD=your-mailgun-smtp-password
POSTFIX_SMTP_TLS=encrypt

Amazon SES:

Terminal window
POSTFIX_RELAYHOST=[email-smtp.us-east-1.amazonaws.com]:587
POSTFIX_RELAYHOST_AUTH_ENABLE=true
POSTFIX_RELAYHOST_USERNAME=your-ses-smtp-username
POSTFIX_RELAYHOST_PASSWORD=your-ses-smtp-password
POSTFIX_SMTP_TLS=encrypt

Troubleshooting

SymptomSolution
Connection refused to databaseVerify DB_HOST and DB_PORT match your MySQL deployment. For Klutch.sh TCP apps, use port 8000.
Emails not forwardingCheck MX records point to your server. Verify Postfix is running in container logs.
DKIM validation failsEnsure DKIM keys are generated and DNS TXT record matches /data/dkim/example.com.txt.
Outbound emails rejectedConfigure an SMTP relay (SendGrid, Mailgun, SES) to bypass port 25 restrictions.
APP_KEY missingGenerate with echo "base64:$(openssl rand -base64 32)" and add to environment variables.
Registration disabledSet ANONADDY_ENABLE_REGISTRATION=true or create users via anonaddy:create-user command.
Data lost after redeployEnsure /data is mounted to a persistent volume.

Security best practices

  • Generate strong secrets: Use long, random strings for APP_KEY and ANONADDY_SECRET.
  • Use Klutch.sh secrets: Mark database passwords, API keys, and secrets as encrypted in the environment variables UI.
  • Disable registration: Set ANONADDY_ENABLE_REGISTRATION=false after creating your account if running a private instance.
  • Enable DKIM signing: Configure Rspamd and DKIM to improve email deliverability and prevent spoofing.
  • Regular backups: Back up the /data volume regularly, especially DKIM keys.
  • Monitor logs: Check container logs for failed deliveries or authentication issues.

Next steps

  • Review the Monitoring guide to set up log streaming and alerts.
  • Configure a custom domain using the Custom Domains documentation.
  • Explore AnonAddy’s browser extension for quick alias generation.
  • Set up the official Android or iOS apps for mobile access.