My opinionated ruby on rails template
README
+223
-4
+223
-4
README.md
+223
-4
README.md
···
1
-
# boxcar
1
+
# 🚃 boxcar
2
+
3
+
A production-ready, opinionated Rails 7+ application template with 24 integrated modules for authentication, authorization, monitoring, and more.
4
+
5
+
Inspired by [@nora](https://github.com/24c02)'s [thirdrail](https://github.com/24c02/thirdrail).
6
+
7
+
## Features
2
8
3
-
my opinionated rails template for my projects.
9
+
| Category | Modules |
10
+
|----------|---------|
11
+
| **Auth & Security** | Custom auth, Pundit, Lockbox encryption, rate limiting |
12
+
| **Admin Dashboards** | Blazer, Flipper, Rails Performance, Mission Control |
13
+
| **Data Management** | Soft deletes, audit trails, friendly URLs, full-text search |
14
+
| **Observability** | Health checks, analytics, console auditing, StatsD metrics |
15
+
| **Infrastructure** | Redis, PostgreSQL multi-db, Solid Queue, Tailwind CSS |
4
16
5
-
## usage
17
+
## Quick Start
6
18
7
-
```zsh
19
+
```bash
8
20
rails new myapp \
9
21
--no-rc \
10
22
--skip-kamal \
···
23
35
-m https://raw.githubusercontent.com/jaspermayone/boxcar/main/template.rb
24
36
```
25
37
38
+
After generation:
39
+
40
+
```bash
41
+
cd myapp
42
+
bin/setup
43
+
bin/dev
44
+
```
45
+
46
+
## What's Included
47
+
48
+
### Authentication & Authorization
49
+
50
+
- **Custom Authentication** — Cookie-based sessions with bcrypt, no Devise dependency
51
+
- **User Roles** — Four-tier system: `user`, `admin`, `super_admin`, `owner`
52
+
- **Pundit** — Policy-based authorization with sensible defaults
53
+
- **Rate Limiting** — Rack::Attack throttling for login attempts and suspicious requests
54
+
55
+
### Security
56
+
57
+
- **Lockbox** — Field-level encryption (`encrypts :ssn`)
58
+
- **BlindIndex** — Search encrypted fields without decryption
59
+
- **InvisibleCaptcha** — Honeypot spam protection
60
+
- **Strong Migrations** — Prevents dangerous migrations in production
61
+
62
+
### Admin Dashboards
63
+
64
+
All mounted under `/admin` with role-based access:
65
+
66
+
| Dashboard | Path | Access | Purpose |
67
+
|-----------|------|--------|---------|
68
+
| Blazer | `/admin/blazer` | admin+ | SQL-based analytics |
69
+
| Flipper | `/admin/flipper` | super_admin+ | Feature flags |
70
+
| Performance | `/admin/performance` | admin+ | Request monitoring |
71
+
| Jobs | `/admin/jobs` | admin+ | Background job dashboard |
72
+
| Console Audits | `/admin/console_audits` | super_admin+ | Rails console access logs |
73
+
74
+
### Data Features
75
+
76
+
- **Public IDs** — Hashid-based IDs for URLs (`usr_abc123` instead of `1`)
77
+
- **Paper Trail** — Automatic audit logging for model changes
78
+
- **Soft Delete** — `acts_as_paranoid` with recovery support
79
+
- **Friendly ID** — SEO-friendly URL slugs with history
80
+
- **pg_search** — PostgreSQL full-text search with ranking
81
+
82
+
### Background Jobs
83
+
84
+
- **Solid Queue** — Database-backed job processing (no Redis required for jobs)
85
+
- **Mission Control** — Web UI for job monitoring and management
86
+
87
+
### Monitoring & Analytics
88
+
89
+
- **Health Checks** — `/health` endpoint with database, cache, and Redis checks
90
+
- **Ahoy Analytics** — Visit and event tracking with email integration
91
+
- **StatsD Metrics** — Request timing, custom gauges, Datadog-ready
92
+
- **Console1984** — Encrypted audit logs for Rails console access
93
+
94
+
### Infrastructure
95
+
96
+
- **PostgreSQL** — Multi-database setup (primary, queue, cache, cable)
97
+
- **Redis** — Sessions (db 2), cache (db 1), rate limiting (db 5)
98
+
- **Tailwind CSS** — Pre-configured and ready to customize
99
+
100
+
## Included Concerns
101
+
102
+
Drop these into your models as needed:
103
+
104
+
```ruby
105
+
class User < ApplicationRecord
106
+
include PublicIdentifiable # adds public_id method
107
+
include Auditable # adds audit_trail method
108
+
include SoftDeletable # adds soft delete behavior
109
+
include Sluggable # adds friendly URLs
110
+
include Searchable # adds full-text search
111
+
include Trackable # adds analytics tracking
112
+
include Encryptable # adds encryption DSL
113
+
include Featureable # adds feature flag support
114
+
end
115
+
```
116
+
117
+
## Generators
118
+
119
+
```bash
120
+
# Add soft delete to a model
121
+
rails g soft_delete Post
122
+
123
+
# Add full-text search to a model
124
+
rails g search_index Post title:A content:B
125
+
```
126
+
127
+
## Configuration
128
+
129
+
### Required Credentials
130
+
131
+
Set these in `config/credentials.yml.enc`:
132
+
133
+
```yaml
134
+
hashid_salt: "your-random-salt-here"
135
+
136
+
lockbox:
137
+
master_key: "generate-with-lockbox-gem"
138
+
139
+
blind_index:
140
+
master_key: "generate-with-blind-index-gem"
141
+
```
142
+
143
+
### Environment Variables
144
+
145
+
```bash
146
+
# Health check authentication (production)
147
+
HEALTH_CHECK_USER=monitor
148
+
HEALTH_CHECK_PASSWORD=secret
149
+
150
+
# Redis
151
+
REDIS_URL=redis://localhost:6379
152
+
153
+
# StatsD (optional)
154
+
STATSD_HOST=localhost
155
+
STATSD_PORT=8125
156
+
```
157
+
158
+
## Routes Overview
159
+
160
+
```
161
+
/ # Your app
162
+
/sign_in # Authentication
163
+
/sign_up # Registration
164
+
/health # Health checks (public)
165
+
/health/all # All health checks
166
+
/admin # Admin namespace
167
+
/admin/users # User management
168
+
/admin/blazer # SQL analytics
169
+
/admin/flipper # Feature flags
170
+
/admin/performance # Request monitoring
171
+
/admin/jobs # Background jobs
172
+
/admin/console_audits # Console access logs
173
+
```
174
+
175
+
## Development Tools
176
+
177
+
Automatically configured:
178
+
179
+
- **Bullet** — N+1 query detection
180
+
- **LetterOpener** — Email preview at `/letter_opener`
181
+
- **Query Count** — SQL query logging
182
+
- **Annotate** — Schema comments in models
183
+
- **Pry** — Enhanced Rails console
184
+
185
+
## Customization
186
+
187
+
### Adding a New Module
188
+
189
+
1. Create `your_module.rb` in the template root
190
+
2. Use the Rails template DSL:
191
+
192
+
```ruby
193
+
# your_module.rb
194
+
say "Installing YourModule...", :green
195
+
196
+
gem "some_gem"
197
+
198
+
after_bundle do
199
+
generate "some_gem:install"
200
+
201
+
initializer "your_module.rb", <<~RUBY
202
+
# Configuration here
203
+
RUBY
204
+
end
205
+
206
+
say "YourModule installed!", :green
207
+
```
208
+
209
+
3. Apply it in `template.rb`:
210
+
211
+
```ruby
212
+
apply "your_module.rb"
213
+
```
214
+
215
+
### Creating a New Module via Command
216
+
217
+
```bash
218
+
# Uses the /new-module slash command
219
+
/new-module notifications
220
+
```
221
+
222
+
## Architecture Decisions
223
+
224
+
- **No Devise** — Custom auth for full control and simplicity
225
+
- **No Sidekiq** — Solid Queue uses PostgreSQL, one less dependency
226
+
- **No Sprockets** — Modern asset pipeline with import maps or bundler
227
+
- **PostgreSQL Required** — Leverages pg_search, Row Level Security, advisory locks
228
+
229
+
## Requirements
230
+
231
+
- Ruby 3.2+
232
+
- Rails 7.1+
233
+
- PostgreSQL 14+
234
+
- Redis 7+
235
+
- Node.js 18+ / Bun
236
+
237
+
## License
238
+
239
+
MIT
240
+
241
+
## Acknowledgments
242
+
243
+
- Inspired by [@nora](https://github.com/24c02)'s [thirdrail](https://github.com/24c02/thirdrail)
244
+
- Built with gems from the amazing Ruby community