CommandTower is a mountable Rails engine that provides shared platform capabilities for host applications: JWT authentication, RBAC authorization, account/Me surfaces, messaging HTTP (inbox, preferences, endpoints), admin announcements, and shared test factories.
Hosts mount the engine, configure secrets and product policy, and build product features on top—without re-implementing platform foundations.
The engine is opinionated and configurable. Architecture follows a stable layer map (workflows orchestrate; services implement capabilities). See Architecture.
# Gemfile
gem "command_tower"bundle install
bin/rails command_tower:install
bin/rails db:migrate
bin/rails command_tower:doctorFull install, upgrade, configuration, and troubleshooting: Initializing CommandTower.
After install, complete RBAC, feature gates, and a Me smoke check: Host integration guide (start here for a new Rails host).
Controller / Job → Workflow → Shared Sequences / Services → Models & Clients
- Controllers are transport adapters (one workflow per action).
- Workflows orchestrate a business action.
- Services (including
CommandTower::ServiceBase) implement one capability.
See Architecture and ServiceBase.
| Guide | Purpose |
|---|---|
| Host integration | Start here — step-by-step new Rails host path |
| Upgrades | Release upgrade summaries (see 0.10.0) |
| Initializing | Install, configure, migrate, doctor, upgrades |
| Testing | Shared FactoryBot / CommandTower::Testing |
| Architecture | Layer map for hosts and contributors |
| Controllers / routes | Engine route areas (index) |
| API reference | Endpoint catalog (detailed contracts) |
| Extending | Stable extension points / do-not-extend |
| Models | User, UserSecret, reopening classes |
| Authentication | JWT auth quick start |
| Authorization | RBAC quick start |
| Authentication & authorization guide | Deep authn + RBAC |
| Cookie authentication | HttpOnly cookies, CORS, CSRF |
| Sensitive changes | Verifier token / session invalidation |
| Messaging | Current messaging surfaces |
| Pagination | Pagination helpers |
| ServiceBase | Service capability base |
| Password reset workflow | Forgot-password flow |
| Change password workflow | Authenticated password change |
| Email verification workflow | Email verification flow |
See Initializing CommandTower for:
command_tower:install/install:migrations- Configure generator flags (
SKIP_CONFIGURE,SKIP_MOUNT,FORCE) - Schema ownership (AD-SCH-01)
- Secrets and doctor checks
- Existing customized hosts
Shared factories for hosts:
require "command_tower/testing"
CommandTower::Testing.install!Details: Testing with CommandTower.
Engine HTTP coverage lives primarily under spec/requests/. Residual journey coverage may remain under spec/integration_test/.
Engine routes cover Auth, Me (profile, inbox, preferences, phone, Pushover), and Admin messaging announcements. Index: Controllers. Contracts: API reference.
Core models such as User and UserSecret are available for hosts to use and reopen carefully. See Models.
Authentication establishes identity (401 when it fails).
-
Engine controllers use
authenticate_request!/authorize_request!(Authentication/Authorization boundaries) and return the application envelope. -
Host controllers may use provisional
before_action :authenticate_user!(failure shapes can differ — see the deep guide). -
Quick start: Authentication
-
Deep guide: Authentication & authorization
-
Web / SPA cookies: Cookie authentication
Cookie mode supports HttpOnly JWT cookies, SameSite, optional double-submit CSRF, and secure cookies in production.
Authorization establishes permission after authentication (403 when it fails).
Engine defaults ship owner and admin (announcements). Hosts must supply rbac_groups.yml entities for Me/Auth surfaces (fail-closed). Host controllers may use provisional authorize_user! after authenticate_user!.
- Quick start: Authorization
- Deep guide: Authentication & authorization
JWT tokens embed a verifier_token bound to the user. Rotating the verifier invalidates outstanding sessions. See Sensitive changes.
Modern messaging surfaces: Me Inbox consume, Produce / ProduceMany emit, admin announcements. See Messaging.
Pagination helpers are available for controllers and services. See Pagination.
CommandTower::ServiceBase adds logging and argument validation for service classes under workflows. See ServiceBase.
MIT — see MIT-LICENSE.