Deployment & Infrastructure

Production hosting on Railway, DNS configuration, environment variables, and Resend domain setup.

This document outlines the deployment topology, cloud infrastructure, and configuration settings required to run Flockbase in production.

Production Topology (Railway)

Flockbase is designed to run on Railway as four interconnected services:

                          ┌───────────────────────────┐
                          │   Railway Cloud Project   │
                          └─────────────┬─────────────┘
                                        │
           ┌────────────────┬───────────┴───────────┬────────────────┐
           ▼                ▼                       ▼                ▼
     PostgreSQL        Core API               Web Dashboard    Documentation
      Database         (NestJS)               (Vite React)      (Fumadocs)
     pg-standard     api.flockbase.live     flockbase.live    docs.flockbase.live

Domain Architecture

Domain	Service Target	Purpose
`flockbase.live`	`church-app/frontend`	Main web dashboard for administrators, leaders, and workers.
`docs.flockbase.live`	`docs`	Public Fumadocs documentation engine.
`notifications.flockbase.live`	Resend DNS (TXT / CNAME)	Transactional email sending subdomain for invites and credentials.
`api.flockbase.live`	`church-app/backend`	NestJS REST API server.

Environment Variables Reference

Backend (`church-app/backend`)

Variable	Required in Prod	Description	Example
`DATABASE_URL`	Yes	PostgreSQL connection string.	`postgresql://user:pass@host:5432/db`
`JWT_SECRET`	Yes	Secret key for signing access tokens.	`super-secret-hex-string`
`TERMII_API_KEY`	Yes	API key from Termii developer dashboard.	`tlv_s5d_...`
`TERMII_SENDER_ID`	Yes	Approved alphanumeric SMS sender tag.	`Flockbase`
`RESEND_API_KEY`	Yes	Resend API key for dispatching emails.	`re_123456789...`
`RESEND_FROM_EMAIL`	Yes	Sender email address.	`noreply@notifications.flockbase.live`
`APP_BASE_URL`	Yes	Base URL for generated invite & login links.	`https://flockbase.live`
`NODE_ENV`	Yes	Set to `production` in live environments.	`production`

In development environments, leave TERMII_API_KEY unset. The backend automatically switches to local OTP stubbing and includes devOtpCode in login responses, saving SMS credits.

Documentation (`docs`)

The documentation site is a standard Next.js application:

Root Directory: docs
Build Command: npm run build
Start Command: npm run start
Port: 3000

Resend Email DNS Configuration

To send transactional emails from notifications.flockbase.live:

In the Resend Dashboard, add domain notifications.flockbase.live.
In your DNS provider (e.g., Cloudflare, Namecheap, Route53), configure:
- SPF (TXT): Points to v=spf1 include:resend.com ~all
- DKIM (CNAME): Configures cryptographic signing records provided by Resend.
Inbound Receiving: As this domain is dedicated strictly to outbound transactional notifications (worker invitations and admin credentials), inbound email routing and MX receiving are not required.