Configure credentials

The next thing that's stopping us from charging money and delivering our software service right away is configuring the app to use our credentials.

We need, for example, to configure our Stripe API keys in the project so we can start processing payments; or our S3 access keys so we can upload and save attachments like user avatars.

Credentials are secure and encrypted

Credentials in RailsFast are encrypted. They can only be decrypted with the random encryption key (config/master.key) that was generated uniquely for you upon project setup (when we ran bin/railsfast init in the quickstart). This is a secure way to store private & sensitive credentials like access and API keys, without risking leaking them in plaintext in the codebase. No one can read your credentials even if they get access to the encrypted file (credentials.yml.enc), because they don't have the decryption key.

How to edit the encrypted credentials file

The RailsFast setup also generated a sample credentials file for you, to help you understand how the credentials file should be used in your project.

You'll see it's very straightforward. To view and edit your project credentials, run:

EDITOR="cursor --wait" bin/rails credentials:edit

And you'll view the decrypted credentials, ready to edit.

To save changes after editing, just save the file and close it, and the credentials will automatically get encrypted back, ready to be used by your app.

# set-stripe-key.rb: surgical TEXT substitution on the decrypted tempfile
# text = File.read(ARGV[0])
# abort("pattern not found, file untouched") unless text.sub!("private_key: sk_live_abc123", "private_key: #{ENV.fetch("STRIPE_KEY")}")
# File.write(ARGV[0], text)
EDITOR="ruby set-stripe-key.rb" bin/rails credentials:edit

How the credentials file is organized

If you look at the credentials file, you'll see it's organized by environments: shared, production, and development.

You may (and probably should) have different credentials for your development and production environments. For example, for Stripe, you should use your sandbox / test keys in development; and you should only use the live keys in production, exclusively.

For some other services, this production vs development distinction may not make much sense, so to avoid duplication you can just put those credentials under the shared block, and both production and development will get them automatically.

I've included a sample demoservice to showcase how shared credentials work. You can also override any part of a shared credentials block like demoservice per environment, while the rest will be kept the same. In any case, demoservice is just there for demoing purposes: you can remove it.

Add all the necessary credentials

If you followed the Prerequisites section, you should already have accounts in all the key services we're going to use, so now it's just a matter of going service by service generating the right keys and plugging them in the right place.

For your RailsFast app to fully work, we'll need at least:

• AWS: we'll just use AWS SES for sending emails. I'm not a fan of AWS, but SES is probably the cheapest & most reliable emailing service out there.
  • Inside your AWS Dashboard, navigate to AWS SES (Simple Email Service)
    • Add your domain in SES > Configuration > Identities and create all required DNS records
    • For more detailed instructions, follow our perfect emailing guide and you'll also achieve a 10/10 deliverability score in your emails
  • Now move away from SES and navigate to AWS IAM to generate an Access Key and Secret Access Key for SES
    • Create a new IAM user
    • Name it something descriptive like yourprojectname-production
    • Give it enough SES permissions to send emails
      • To do that, create a new policy, click on the [ Create policy ] button
      • In the "Specify permissions window, switch from "Visual" to "JSON" and paste the following contents:

      {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
              "ses:SetIdentityMailFromDomain",
              "ses:SendEmail",
              "ses:SendTemplatedEmail",
              "ses:SendCustomVerificationEmail",
              "ses:SendRawEmail",
              "ses:SendBulkTemplatedEmail",
              "ses:SetIdentityDkimEnabled",
              "ses:SetActiveReceiptRuleSet"
            ],
            "Resource": "*"
          }
        ]
      }

      • Give it a descriptive name like ses-send-email-policy and create the policy
    • Back on the create user screen, attach the new created policy to the user, and create it
    • Once the user is created, click it to access the user details screen, navigate to the "Security credentials" tab, and create a new Access Key. When asked, select "Other" as your reason (your reason is direct AWS API calls, but that's not listed)
    • Create the Access Key and copy the access key and private key to your RailsFast project's credentials file

• Cloudflare: DNS + DDoS protection, Turnstile for anti-bot signups, R2 for S3-compatible storage (for storing avatars, user uploads, etc.)
  • R2: create an R2 bucket for your project. Then, on the R2 Overview screen, under the Account Details box, you'll see the "API Tokens" row and next to it, a {Manage} button, click it. Now in the Manage R2 API tokens screen, create a User API Token for your bucket (give it Object Read & Write permissions, click "Apply to specific buckets only" and specify just your bucket). Create the API Token and copy and paste the account_id, access_key_id, secret_access_key and bucket name, and paste them in the right place in your credentials file. Go back to the R2 Overview screen, copy your Cloudflare account ID and paste it in the corresponding spot in the credentials file too. You only need to do this for production, not for development.
  • Turnstile: create a Turnstile widget to get your Turnstile site key and secret key. This will be used to protect your auth / signup forms from bots. As with R2, Turnstile credentials are only needed in production, not in development. You just need the site and secret keys, you don't need to do anything else with the widget, all is already configured and wired in RailsFast for you.

CFA="$(cat ~/.config/railsfast/cloudflare_account_token)"
# 1. Create the bucket (locationHint is advisory: Cloudflare may place the
#    bucket in a nearby region; options: weur/eeur/wnam/enam/apac):
curl -s -X POST "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/r2/buckets" \
  -H "Authorization: Bearer $CFA" -H "Content-Type: application/json" \
  --data '{"name":"myproject","locationHint":"weur"}'
# 2. The token IS your S3 credential pair (documented R2 pattern):
#    access_key_id     = the token's ID:  curl -s .../user/tokens/verify | jq -r .result.id
#    secret_access_key = SHA-256 of the token value:  printf '%s' "$CFA" | shasum -a 256
# 3. Create the Turnstile widget (returns sitekey + secret):
curl -s -X POST "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/challenges/widgets" \
  -H "Authorization: Bearer $CFA" -H "Content-Type: application/json" \
  --data '{"name":"myproject","domains":["myproject.com"],"mode":"managed"}'

• Google (optional): one-click "Continue with Google" sign-in on your signup and login forms. Skip it and nothing breaks: the feature simply stays off, buttons and all.

  • In the Google Cloud console, create an OAuth client ID (application type: Web application). One client powers both the button and Google One Tap, so register:
    • Authorized JavaScript origins: https://YOUR-DOMAIN-HERE (and http://localhost plus http://localhost:3000 for development)
    • Authorized redirect URIs: https://YOUR-DOMAIN-HERE/users/auth/google_oauth2/callback (the button) and https://YOUR-DOMAIN-HERE/users/auth/google_one_tap (One Tap)
  • Paste the client ID and client secret into the google: → oauth: block of your production credentials. Add the same block to development (with the http://localhost:3000/... redirect URIs) if you also want it while developing
  • Full walkthrough, including the consent screen and how account linking works: Social login

• Stripe: payment processing

  • Generate a publishable and a private key (both in live and sandbox mode, for production and development, respectively)
  • Create a webhook in live mode (webhook URL: https://YOUR-DOMAIN-HERE/pay/webhooks/stripe), and add the webhook signing secret in production. Stripe pins an API version on each endpoint when you create it. Use a version from 2025-03-31 onward (a new endpoint normally gets the current one); on an older endpoint Pay skips the payment-failed email and the invoice sync. See Payments.
  • Install the Stripe CLI and add the development webhook signing secret to development

• Push notifications (optional): only if you ship the native iOS and Android apps and want to send them notifications. Leave it out and push simply stays off.
  • Secrets go in the environment's credentials block, under action_push_native:: apns.key_id and apns.encryption_key (the contents of the .p8 key from Apple Developer → Keys), and fcm.encryption_key (the Firebase service-account JSON). Values still ending in abc123 count as unset.
  • The non-secret half: the APNs team id and topic come from the iOS app id you already configured for app links (APNS_TOPIC overrides the topic), and the Firebase project id comes from ANDROID_FIREBASE_PROJECT_ID or native.android.firebase_project_id in config/railsfast/railsfast.yml.
  • bin/railsfast doctor lists both as optional services. The full setup, including the migrations and how to send a notification: Notifications.

Configure database backups

RailsFast ships by default with automatic database backups. All your user's data gets backed up regularly outside of your server, so in case of disaster you can recover all your data and put your app back up. However, for this to work you need to let your app know where those backups should be uploaded to.

Luckily for us, we can use any S3-compatible storage solution for this. So, since we already have an AWS and a Cloudflare account, we could just use AWS S3 or Cloudflare R2 for our backups and be done with it. There's nothing wrong with that.

However, if you're like me and you want to add an extra bit of resilience to your setup (in the improbable case your AWS or Cloudflare accounts get compromised because you're already using them for other things), you can keep your backups in a completely different service that we're only going to use for backups. I use Backblaze B2 for that. Backblaze B2 is S3-compatible just like AWS S3 or Cloudflare R2, and they also have a free tier that makes your backups free or close to free as long as they're not too big.

Whatever the service you end up using for storing backups (again, AWS S3 and Cloudflare R2 are both good options if you don't want to complicate things early), you just need to add the S3-compatible credentials in the designated files under config/backups:

• s3_access_key.key
• s3_bucket.key
• s3_region.key
• s3_secret_access_key.key

These credentials are the same for any S3-compatible storage service. Just replace the placeholder text in each file with your credentials, re-deploy the backups service with kamal accessory reboot pg-backup, and you'll be automatically backing up your entire production database every night.

bin/kamal accessory exec pg-backup --reuse "/backup-scripts/backups.sh"
# confirm the dumps landed (B2 endpoint; <region> is the value in config/backups/s3_region.key)…
aws s3 ls s3://your-backups-bucket --recursive \
  --endpoint-url https://s3.<region>.backblazeb2.com --region <region>
# …then do the scratch-database restore drill from the runbook guide

If you want to adjust when to do backups, how often to do them, and how many backups to keep, you just need to adjust the pg-backup config in config/deploy.yml. Make sure to reboot the backups service after you make changes:

bin/kamal accessory reboot pg-backup

Verify your backups are actually running

A backup pipeline can die without telling anyone: the container gets rebooted and never comes back, credentials rot, or the cron runs but uploads a tiny garbage file instead of a real dump. As a cautionary tale, a production app once ran seven months with silently dead backups. Every dashboard was green the whole time, because nothing that reported health shared the backup container's fate. Nobody deletes their database on a day their backups happen to be working; the day you need a dump is precisely a day nothing else went right.

That's why current templates ship a backup tripwire: an allgood check called "Database backups are fresh" on your /healthcheck page (the code lives in app/services/backup_freshness.rb). The app itself lists the backup bucket (the listing is cached for 30 minutes) and goes red when the newest main database dump is older than 26 hours (BACKUP_MAX_AGE_HOURS) or not bigger than 1 MB (BACKUP_MIN_BYTES: real dumps are megabytes; a "successful" run that uploads a 35-byte metadata file is a dead backup wearing a green light). Since your uptime monitor is already watching /healthcheck, a dead backup pipeline now pages you within a day instead of seven months later. And if the tripwire itself dies, it takes the healthcheck page with it, so its own death is visible too.

To arm it, the check needs its own key that can only list file names. Do not reuse the backup credentials above. In Backblaze B2 (equivalent steps exist in S3/R2):

1. Application Keys → Add a New Application Key
2. Allow access to Bucket(s): your backup bucket only
3. File name prefix: your app's backup prefix (your app name, e.g. myapp/)
4. Capabilities: listFiles only: no read, no write, no delete
5. Save the two values into gitignored files: the keyID into config/backups/monitor_key_id.key and the applicationKey into config/backups/monitor_application_key.key, then deploy. .kamal/secrets already reads both files.

The check fails closed: with no monitor key configured, it reports failing on /healthcheck in production rather than staying silently green. The deploy itself still goes through, because .kamal/secrets falls back to an empty value while the two key files are missing, so expect your uptime monitor to flag the check until step 5 is done. That's deliberate: an unarmed tripwire that looks armed is worse than none.

The tripwire proves your backups keep existing. It doesn't prove they restore; that's what the drill in the tip above is for: do the scratch-database restore once, then let the tripwire watch the pipeline day to day.