Deployment checklist

Check the services your Rails host needs before evaluating AddAuth in a deployed environment.

Verify your deployment

AddAuth uses local integration tests for release acceptance. Your app supplies its production mail provider, queue, cache, proxy and recovery process. Verify those integrations and the browsers you support before enabling sign-in for users. Check package availability before installing.

Prepare the required services

Service	What to configure	What to verify
HTTPS	Set `base_url` to your public HTTPS origin.	Delivered links open the correct host.
Shared cache	Use a shared, atomic counter store for `rate_limit_store`; see the configuration below.	Rate limits survive requests hitting different servers.
Durable queue	Configure an Active Job backend such as Solid Queue or Sidekiq and run its workers.	Pending delivery survives an app restart.
Mail transport	Configure Action Mailer, your sender and provider credentials.	A real mailbox receives the message; failures remain visible.
Database	Review and apply generated migrations.	Doctor and actual sign-in/session flows succeed.

Configure the host

The example uses a separate Redis counter store. Add gem "redis", "~> 5.4" to the host Gemfile, run bundle install, and supply AUTH_REDIS_URL through deployment configuration. All web, worker and maintenance processes must use the same counter store and namespace.

AddAuth.configure do |config|
  config.base_url = "https://accounts.example.com"
  config.mail_from = "Accounts <sign-in@example.com>"
  config.rate_limit_store = ActiveSupport::Cache::RedisCacheStore.new(
    url: ENV.fetch("AUTH_REDIS_URL"), namespace: "add_auth"
  )
end

Replace example hosts and senders. Store provider credentials in your deployment’s secret store. Keep Action Mailer delivery errors enabled so AddAuth can distinguish failures from delivery success.

The default eligibility callback permits any matching account. If your app has confirmed, disabled or locked accounts, configure eligible using your app’s actual policy. See host settings.

Choose atomic abuse counters

A shared cache alone is insufficient: initialization, increment and expiry must remain correct when several processes hit a new key together. Local acceptance verifies these operations with Rails RedisCacheStore. A custom adapter must prove the same contract, including unavailable-store behavior.

Do not use Solid Cache for rate_limit_store. Solid Cache 1.0.10 can lose a simultaneous first increment on PostgreSQL. Keep it for normal application caching and configure separate abuse counters as above. AddAuth 0.2.2 rejects Solid Cache for these counters and doctor explains the separate-store remedy. The older 0.2.1 doctor used a sequential probe that could miss this race. Passing a sequential probe does not establish atomicity for an unknown store.

How the limits apply

Each sign-in, email, recovery and reauthentication request first uses its client IP address’s budget for that action: up to 30 requests in any five-minute window. Only then is a configured captcha checked. The submitted email address’s budget of 5 requests per action is charged only after that check passes. Requests stopped by the IP budget or the captcha do not use up the email address’s budget.

Passkey sign-in option requests have their own IP budget, separate from password sign-in. passkeys.anonymous_limit separately bounds anonymous passkey ceremonies for each IPv4 address or IPv6 /64. Configure Rails’ trusted proxies so request.remote_ip reports the real client, and account for users who share an IP address when setting passkeys.anonymous_limit.

Schedule the delivery sweep

Run this task at least once a minute using your platform’s scheduler:

bin/rails add_auth:deliver_pending

It queues pending sign-in and security mail, removes expired passkey ceremonies and clears expired delivery ciphertext in bounded batches. Configure a history retention policy for sessions and receipts. Monitor failed jobs and the scheduler itself. Mail intentionally cancelled by a callback is terminal for that issuance; the sweep will not resend it.

Verify the full journey

Run bin/rails add_auth:doctor and resolve each relevant finding.
Request a link through the deployed app and receive it in a real mailbox.
Confirm the link, visit /sessions, then revoke a second browser’s session and check its next request.
Verify expired and consumed links are rejected and fresh links can be requested.
Exercise password/email sign-in without JavaScript where your captcha policy allows it.
Simulate a worker restart and transport failure in a safe test environment; verify retries and monitoring.

For enabled features, also complete passkey sign-in on your supported physical devices, both recovery policies, a protected write and security mail delivery. Check live captcha success, rejection and provider outage handling with your own configured hostname.

Keep every authentication model on the same database connection pool. Test your shared cache across web instances, trusted proxy and allowed-host settings, and Secure/HttpOnly/SameSite cookies through the actual TLS terminator. Record queue age and delivery latency before selecting alert thresholds.

Plan for existing users

Session adoption signs existing users out unless you configure a bounded legacy bridge. Review the transition before rollout. Do not restore the old authentication path as a routine rollback after bearer sessions are adopted; plan recovery without weakening the session boundary.

For subsequent package updates, follow the persisted-host upgrade rehearsal.