How Basefloor is built and deployed — Rails backend via Kamal, frontend via Cloudflare Pages.

Deployment

Basefloor uses a split deployment model: the Rails backend is deployed to a self-hosted server using Kamal, and the Next.js/TanStack frontend apps are statically published to Cloudflare Pages.

Backend — hms-core

Deployment Tool: Kamal

The backend is deployed via Kamal — a Rails-native deployment tool that uses Docker and SSH.

Configuration is in .kamal/ and config/deploy.yml.

Environments

Environment	Branch	URL
Production	`main`	`https://hms-api.kaisersakhi.com`
Staging	`develop`	`https://hms-api-staging.kaisersakhi.com`

Deploying

# First-time setup (runs migrations, sets secrets)
kamal setup

# Deploy a new release
kamal deploy

# Deploy to staging
kamal deploy --destination staging

Secrets & Credentials

Rails credentials are stored environment-specific:

config/credentials/production.yml.enc
config/credentials/staging.yml.enc

Two environment variables must be set on the server:

RAILS_ENV=production
RAILS_MASTER_KEY=<your_key>

Do not commit master.key or raw credentials to Git.

Database Migrations

Migrations run automatically during kamal deploy. To run them manually:

kamal exec --reuse "bin/rails db:migrate"

Background Jobs

Solid Queue is used for background job processing. It runs as a separate process managed by Kamal's accessories:

kamal accessory boot solid-queue

Frontend — Cloudflare Pages

Both the TanStack web app and the Next.js marketing site are deployed to Cloudflare Pages.

Repositories & Projects

App	GitHub Repo	CF Pages Project
Marketing	`basefloor-UI` (apps/marketing)	`basefloor-marketing`
Product Docs	`basefloor-product-docs`	`basefloor-product-docs`
Dev Docs	`basefloor-dev-docs`	`basefloor-dev-docs`

Build Settings

For each Cloudflare Pages project, set:

Setting	Value
Framework preset	`Next.js (Static HTML Export)`
Build command	`npm run build`
Output directory	`out`
Node.js version	`22`

Environment Variables (Cloudflare Dashboard)

Set these in the Pages project settings:

Variable	Value
`VITE_API_BASE_URL`	`https://hms-api.kaisersakhi.com/api/v1`

Deployment Flow

Push to main branch of the relevant repository
Cloudflare Pages detects the push via GitHub integration
Runs npm run build using the configured settings
Deploys the out/ directory to Cloudflare's global edge network
Live within ~60 seconds

Preview Deployments

Every pull request automatically gets a preview deployment at:

https://<branch>.basefloor-product-docs.pages.dev

This lets you review documentation changes before merging.

CI/CD — GitHub Actions

GitHub Actions handles automated testing and quality checks on every push.

Backend Checks (hms-core)

# .github/workflows/ci.yml
- name: Run RSpec
  run: bundle exec rspec

- name: Run Rubocop
  run: bin/rubocop

- name: Run Brakeman
  run: bin/brakeman --no-pager

Frontend Checks (basefloor-UI)

- name: Type Check
  run: pnpm type-check

- name: Lint
  run: pnpm lint

- name: Build
  run: pnpm build

These checks run on every pull request and must pass before merging to main.

Cloudflare Zero Trust (Dev Docs Access)

The developer documentation site is protected by Cloudflare Access:

Only authenticated GitHub Organization members can access dev-docs.basefloor.app
Authentication flows through Cloudflare Zero Trust using GitHub OAuth
No VPN required — access is managed entirely at the Cloudflare edge

To configure: Cloudflare Dashboard → Zero Trust → Access → Applications → Add an application.

Deployment

On this page