Deploy VoidAuth

Deploy and Host VoidAuth on Railway

VoidAuth is an open-source identity provider for self-hosted applications, with OpenID Connect, users and groups, MFA and passkeys.

About Hosting VoidAuth

This template deploys VoidAuth v1.15.1 with private Postgres 18 and persistent configuration storage. Its compatibility image adds a tested host-only cookie fix to the pinned official image, required for internal OIDC login on Railway subdomains. It generates database and encryption secrets automatically. No external account or email provider is needed to set up the initial administrator.

Common Use Cases

• Centralize sign-in for applications that support OpenID Connect.
• Manage application users, groups, invitations and access policies.
• Offer password, MFA and passkey authentication for your own services.

Dependencies for VoidAuth Hosting

Deployment Dependencies

A Railway account with capacity for two running services and two persistent volumes. Optional email delivery requires your own authorized SMTP provider. Public registration, SMTP and LDAP are disabled by default.

Implementation Details

First login

1. Deploy the template and wait for both services to start.
2. Open the VoidAuth deployment logs. Find the password reset link for the initial administrator. Treat this URL as a secret. It expires after 24 hours.
3. Open that link, set a strong password, then sign in as auth_admin.
4. Rename the administrator or invite your own account and add it to auth_admins. Membership in this group grants full VoidAuth administration.
5. Register your application under OIDC Apps, copy its client credentials into your application, and configure an exact redirect URI. The issuer is https://YOUR-VOIDAUTH-HOSTNAME/oidc. Discovery is at /oidc/.well-known/openid-configuration.

Public self-registration, SMTP and LDAP are disabled. No external account or email provider is required for initial setup. Invitations can be shared directly as links. Email delivery needs your own authorized SMTP provider; configure only requested account and transactional messages.

If the initial reset link expires, temporarily set the VoidAuth service's Railway Start Command to node /app/dist/index.mjs generate password-reset auth_admin and deploy. Copy the new secret reset URL from those deployment logs. This command exits, so that deployment will not pass its healthcheck. Clear the Start Command and deploy normally before opening the reset link. Never leave the reset command configured. The upstream image has no shell, so Railway SSH is not supported.

Services and storage

Railway terminates HTTPS. APP_PORT and PORT are explicitly 3000. /healthcheck is the readiness endpoint, but does not prove authentication or database writes work.

Custom domains and ProxyAuth

For production, choose your permanent authentication domain before registering OIDC clients or passkeys. Add that domain to the VoidAuth service, then set APP_URL=https://auth.example.com and SESSION_DOMAIN=null (the literal string null, meaning host-only cookies). Apply changes and deploy again. Update client issuer configuration to match. Passkeys are domain-bound and may need re-enrollment after a domain change.

This template uses SESSION_DOMAIN=null to create host-only cookies. Setting the full hostname explicitly triggers an upstream v1.15.1 domain-validation bug on Railway subdomains; do not replace null with the generated hostname. The compatibility image also fixes upstream's internal OIDC redirect check for host-only cookies. It accepts the exact configured application hostname and rejects other hosts. Cross-subdomain ProxyAuth requires a domain you own and an explicitly chosen shared cookie domain, such as example.com, plus a correctly configured reverse proxy. Do not share cookies across Railway tenant domains. Keep the upstream trusted-proxy defaults unless you have verified your proxy topology; never blindly trust all forwarded headers.

Backups, upgrades and recovery

Back up both volumes and the STORAGE_KEY variable before upgrades. The key encrypts database secrets; losing or casually changing it makes those secrets unreadable. Keep it outside public source control. A database backup without its key is incomplete.

Pin image versions, read upstream release notes, and test migrations on a restored copy first. Keep a single VoidAuth replica with this mounted configuration volume. Do not enable serverless sleeping for an identity provider expected to serve logins continuously.

If deployment fails before Postgres is ready, retry after Postgres starts. If you change variables, apply them in a fresh deployment. If login redirects fail, check that APP_URL, SESSION_DOMAIN, the browser hostname and OIDC redirect URIs agree.

Security and scope

VoidAuth supports OIDC, users and groups, MFA, and passkeys. Upstream explicitly states that it has not been audited. Evaluate it for your security requirements before using it for sensitive production identity.

LDAP is not exposed by this template. SMTP delivery, passkeys on physical devices and external reverse-proxy integrations require separate verification. Running services and stored volumes incur Railway usage charges.

Why Deploy VoidAuth on Railway?

Railway provides HTTPS domains, private service networking, persistent volumes and deployment logs. This template wires the application to its database and generates its secrets, leaving account setup and OIDC application registration to you.

Upstream source | Documentation