Skip to content

simplelogin-setup.md

Latest commit

 

History

History
115 lines (74 loc) · 4.49 KB

simplelogin-setup.md

File metadata and controls

115 lines (74 loc) · 4.49 KB
Raw

SimpleLogin AIO Setup Guide

This guide covers the minimum pieces required to make simplelogin-aio work on Unraid.

1. Pick Your Hostnames

You normally want:

  • app.example.com for the web UI
  • mail.example.com for inbound SMTP delivery

Set the Unraid template like this:

  • URL=https://app.example.com
  • EMAIL_DOMAIN=example.com
  • SUPPORT_EMAIL=support@example.com (use a mailbox that already exists)

EMAIL_DOMAIN becomes a SimpleLogin alias domain. Do not use an address on that same domain as the first account mailbox; register with an existing external mailbox you can already receive, then add alias-domain routing inside SimpleLogin after activation.

2. Add DNS Records

At minimum, add:

  • A or AAAA record for app.example.com
  • A or AAAA record for mail.example.com
  • MX record for example.com pointing to mail.example.com
  • SPF TXT record on example.com
  • DMARC TXT record on _dmarc.example.com

SimpleLogin will also need DKIM once the container has booted and generated its keys.

After first boot, the wrapper stores DKIM material under /appdata/dkim and symlinks the active keys into the in-container paths SimpleLogin expects.

3. Forward Mail Traffic

Inbound internet mail must reach the Unraid host:

  • forward TCP port 25 from your router/firewall to the Unraid server

If your ISP blocks outbound port 25, choose a relay provider in the template:

  • brevo
  • protonmail
  • gmail
  • mailgun
  • custom

If your ISP does not block outbound mail, direct can work.

Use the template dropdown values as-is for enum-style fields. Do not free-type custom values into fields like RELAY_MODE or ADMIN_FIDO_REQUIRED.

Advanced users can also skip the wrapper relay shortcuts and use the expanded Advanced View settings for direct upstream env overrides.

4. Start the Container

On first boot the container will:

  • initialize PostgreSQL if DB_URI is not set
  • start Redis if REDIS_URL is not set
  • write the runtime .env
  • configure Postfix
  • apply alembic upgrade head
  • run init_app.py once

The first start can take longer than a normal restart because the internal database is being prepared.

The wrapper now validates the rendered .env before starting the web app, job runner, email handler, or Postfix. If an enum-style value is invalid, startup stops once with a fatal error instead of leaving the dependent services in wait loops.

5. Confirm It Is Healthy

After the container comes up:

  • open the web UI on port 7777
  • keep DISABLE_REGISTRATION=true (default) to prevent public sign-up
  • only set DISABLE_REGISTRATION=false temporarily if you need web sign-up for first boot; once your first account exists, set it back to true and restart
  • confirm /health responds
  • check the logs for any Postfix relay or DNS warnings
  • check /appdata/sl and /appdata/postgres were populated

6. Advanced Overrides

You can point the container at external services:

  • set DB_URI to skip the internal PostgreSQL daemon
  • set REDIS_URL to skip the internal Redis daemon

The template also exposes the full upstream example.env feature surface in Advanced View, including:

  • alias domain behavior and onboarding controls
  • social/OIDC auth providers
  • hCaptcha, HIBP, SpamAssassin, Plausible, and Sentry
  • AWS, Paddle, Coinbase, and file-path based advanced settings
  • optional /custom-assets mounting for custom words files or key material

Unless you have already planned around it, leave ADMIN_FIDO_REQUIRED=none. Turning it on without intentional admin security-key enrollment just creates unnecessary lockout risk.

This keeps the Unraid template flexible without forcing beginners into a multi-container setup.

7. Features That Do Not Need Extra Containers

SimpleLogin's official docs also cover several features that are handled inside the app itself after deployment. These do not require extra database, cache, or helper containers in this AIO image:

  • custom domains and additional alias domains
  • catch-all and mailbox routing behavior
  • reverse aliases and reply handling
  • multiple mailboxes
  • alias directories and other UI-managed account features

Those are application features, not separate infrastructure services. The AIO image already bundles the core self-hosted infrastructure pieces that normally force extra containers:

  • PostgreSQL
  • Redis
  • Postfix

So for the normal self-hosted path, users should not need to stand up additional DB/cache/mail-routing containers unless they deliberately choose external overrides like DB_URI or REDIS_URL.