Setup: Mobayilo (Rails 8.1 + Hotwire + Tailwind)

Setup: Mobayilo (Rails 8.1 + Hotwire + Tailwind)

This repo currently contains specifications and planning docs. This SETUP.md defines the intended local/dev setup for the Rails implementation.

1) Prerequisites

• Ruby: 3.3+ (recommended: 3.4.x)
• Rails: 8.1.x
• PostgreSQL: 15+ (recommended: 16/17)
• Node/Bun: required if using jsbundling-rails (recommended for Twilio Voice SDK)
• Tailwind CSS (offline): tailwindcss-rails provides the CSS build without npm.
• Stripe CLI: optional, for local webhook forwarding
• ngrok / cloudflared: for Twilio webhooks in local dev

2) Create the Rails app (recommended defaults)

If you’re starting from scratch:

• Use Tailwind + Hotwire and ESBuild (Twilio Voice SDK works best with a real JS bundler).
• Use Rails defaults where possible (Propshaft + Solid Queue) to keep the stack minimal.

Example:

• rails new mobayilo --database=postgresql --css=tailwind --javascript=esbuild
• cd mobayilo

3) Environment variables

Create .env (or use your preferred secrets manager). Minimum set:

App

• APP_HOST=localhost:3000
• APP_PROTOCOL=http
• RAILS_ENV=development

Database

• Prefer MOBAYILO_DATABASE_URL=postgres://... if you use shared .env.local files across multiple projects.
• Avoid setting a generic DATABASE_URL to another app’s database when working in this repo.

Twilio (Programmable Voice)

• TWILIO_ACCOUNT_SID=AC...
• TWILIO_AUTH_TOKEN=...
• TWILIO_API_KEY_SID=SK...
• TWILIO_API_KEY_SECRET=...
• TWILIO_TWIML_APP_SID=AP...
• TWILIO_PHONE_NUMBER=+1... (E.164)

Stripe (credits/top-ups)

• STRIPE_PUBLISHABLE_KEY=pk_...
• STRIPE_SECRET_KEY=sk_...
• STRIPE_WEBHOOK_SECRET=whsec_...

Email (pick one)

• SENDGRID_API_KEY=...
• SENDGRID_FROM_EMAIL=support@yourdomain.com

SMTP TLS note (development only)

If you must bypass CRL validation locally, you can set:

• SMTP_DISABLE_CRL_CHECK=true

This sets openssl_verify_mode = VERIFY_NONE in development to unblock local SMTP. Do not use this in production. Remove the flag and restore strict TLS verification.

4) Database setup

• bin/rails db:create
• bin/rails db:migrate
• bin/rails db:seed (rates, default configs)

Note: In development/test, this repo ignores DATABASE_URL unless MOBAYILO_DATABASE_URL is set (see config/initializers/database_url_override.rb).

5) Running the app

Recommended dev entrypoint:

• bin/dev

If you’re not using bin/dev yet:

• bin/rails server

Tailwind (offline-friendly) commands:

• bin/rails tailwindcss:build
• bin/rails tailwindcss:watch

6) Twilio configuration (what to set in Twilio Console)

TwiML Application

Set the Voice URL to your app’s TwiML endpoint (POST), for example:

• https://<YOUR_PUBLIC_HOST>/api/webhooks/twilio/voice

Set the Status Callback URL to your status endpoint (POST):

• https://<YOUR_PUBLIC_HOST>/api/webhooks/twilio/status

Local dev webhooks

Twilio must reach your machine over the public internet:

• Start tunnel: ngrok http 3000
• Use the https://... forwarding URL for the TwiML + status callback URLs above.

7) Stripe configuration (credits)

Webhooks

For local development, you can forward Stripe webhooks:

• stripe listen --forward-to localhost:3000/api/webhooks/stripe

Record the printed whsec_... in STRIPE_WEBHOOK_SECRET.

Events to handle (minimum):

• payment_intent.succeeded
• payment_intent.payment_failed
• charge.refunded

8) Recommended Rails gems (MVP)

• Auth: devise
• Passwordless seats: passwordless (or devise-passwordless)
• Authorization: pundit (optional for MVP, useful for admin)
• Phone validation: phony_rails or global_phone (plus server-side E.164 validation)
• Rate limiting: rack-attack
• Admin: avo (optional; can start with Rails scaffolds/admin namespace)

9) Production notes (high level)

• Enforce HTTPS, HSTS, and strict CSP (Twilio JS SDK will require allowed script/connect sources).
• Store credentials in platform secrets (Render/Fly/Heroku/etc.), not .env.
• Ensure Twilio geo-permissions match your supported destinations.
• Ensure Solid Queue scheduler is running and recurring tasks are loaded (config/recurring.yml).

10) Open choices to confirm

1. JS strategy: ESBuild (recommended) vs importmap?
2. Background jobs: Solid Queue (Rails default).
3. Admin: Avo from day 1, or later?

6.1) Twilio quick test scripts (optional)

One-off outbound call:

• Set env vars: TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER, TWILIO_TEST_TO
• Run: ruby scripts/twilio_make_call.rb

Inbound “answer call” demo (Sinatra + ngrok):

• Run: ruby scripts/twilio_answer_call.rb
• Start tunnel: ngrok http 4567
• Set your Twilio number’s Voice webhook to the ngrok URL