Prepare your Rails host

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

Release acceptance is still open

This is deployment preparation for unreleased 0.2.0.dev. A working local sign-in does not establish production readiness. Test your own mail provider, queue, cache, browser journeys and recovery procedures.

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 cache shared across application instances for `rate_limit_store`.	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

Latchkey.configure do |config|
  config.base_url = "https://accounts.example.com"
  config.mail_from = "Accounts <sign-in@example.com>"
  config.rate_limit_store = Rails.cache
end

Replace example hosts and senders. Store provider credentials in your deployment’s secret store. Keep Action Mailer delivery errors enabled so Latchkey 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.

Schedule the delivery sweep

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

bin/rails latchkey:deliver_pending

It retries pending sign-in delivery and clears expired delivery ciphertext. 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 latchkey: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.

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.