VoidAuth Deployment Guide (Fly.io + Unmanaged PostgreSQL)

Replace voidauth with your own app name (for example: b4iterdev-voidauth) in commands where needed.

Create a Postgres cluster:

fly postgres create --name voidauth-pg --region iad

Save these values from the output (you will use them in Step 4):

• Postgres host
• Postgres password
• Postgres user/database (usually postgres)

fly apps create voidauth
fly volumes create voidauth_config --app voidauth --region iad --size 1

Use the fly.toml in this repo, then update:

app = "voidauth"          # change to your Fly app name
primary_region = "sin"    # change to your preferred region

fly secrets set -a voidauth \
  APP_URL="https://auth.yourdomain.com" \
  STORAGE_KEY="$(openssl rand -hex 32)" \
  DB_HOST="<flycast-postgres-host>" \
  DB_PASSWORD="<postgres-password>"

Optional, set in fly.toml [env] or as secrets:

• APP_TITLE, APP_COLOR, APP_FONT, CONTACT_EMAIL (see commented lines in fly.toml)
• TRUSTED_PROXIES: since v1.15.0 this controls which proxies' client-IP headers are trusted. The default (loopback, linklocal, uniquelocal) already covers Fly's internal proxy addresses, so real client IPs are detected out of the box. Only set it explicitly if you place your own proxy in front of Fly.
• SMTP settings (SMTP_HOST, SMTP_FROM, ...) if you want invitations, verification, or password resets to send email.

Edit files under:

• customization/branding/custom.css
• customization/email_templates/**

At image build time, these are copied into /app/customization-seed. (Do not put these files under /opt because the hardened base image may not preserve/execute those paths as expected.) At startup, they are copied into /app/config (your Fly volume mount) before VoidAuth starts.

fly deploy -a voidauth --ha=false

Get startup logs:

fly logs -a voidauth --no-tail

On first startup, VoidAuth prints a one-time setup link for the initial admin account (auth_admin) to the logs. Copy the link from the log output, open it in a browser to set the admin password, then sign in and immediately create/update your permanent admin user.