# 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`.