Repository navigation
Development
bundle install
bundle exec rake db:migrate RAILS_ENV=test
bundle exec rake test # unit + controller tests (SQLite, no server needed)
bundle exec cucumber # feature tests
bundle exec brakeman -q # static analysis, must report 0 warnings
bundle exec bundle-audit check # dependency CVEsUse the cucumber binary, not rake cucumber:ok — the rake task runs cucumber
in-process and minitest's autorun then dies on cucumber's --profile flag.
config/database.yml uses SQLite for development/test and PostgreSQL for
production. That split hides adapter-specific breakage, because a single-engine run
only ever exercises one of them. It has caused total failures: Event.insertStatement
emitted SQLite ? placeholders through exec_query, Postgres rejected them
outright, and production could not insert a single event while every SQLite job
stayed green.
To run the suite against Postgres locally:
createuser dad && createdb -O dad dad_test
DATABASE_URL=postgres://dad:dad@127.0.0.1:5432/dad_test bundle exec rake db:migrate_from_scratch
DATABASE_URL=postgres://dad:dad@127.0.0.1:5432/dad_test bundle exec rake test
DATABASE_URL=postgres://dad:dad@127.0.0.1:5432/dad_test bundle exec cucumberdb:migrate_from_scratch (not db:migrate) is what builds the partitioned shape the
Postgres tests need. Without DATABASE_URL everything runs on SQLite, and the
partitioning and backup tests skip rather than fail.
Never run rake db:seed against a shared test database. It leaves an admin user
and seeded Jobs behind, and the seed-idempotency test then fails on the next full
run for reasons that look like a code regression but are leftover state.
- Raw SQL uses SQLite
?placeholders and goes throughSqlPlaceholders.query, which rewrites them to$1, $2, …on Postgres. Callingexec_querydirectly with?is a production bug no SQLite-only run can detect. -
extract()is Postgres-only; SQLite rejects it. Dashboard queries bucket hours withsubstr(cast(<ts> as text),1,13)instead. -
db/schema.rbis checked in as the SQLite flavour. Runningdb:migrateagainst Postgres rewrites it withenable_extensionandt.bigint, which breaksdb:schema:loadfor dev/test. Never commit a Postgres-generatedschema.rb. - A failed
CONCURRENTLYindex build leaves anINVALIDindex that keeps its name and thatindex_exists?still reports healthy, wedgingdb:migrate. The CI Postgres job asserts none exist. - A
CHECKconstraint can be created on SQLite but not added byALTER TABLE ADD CONSTRAINT, so20261108000001_add_integrity_constraintsguards itsjobs.frequencyCHECK behind an adapter check. On SQLite the model validation is the only enforcement, which means the SQLite suite cannot prove that branch — only the Postgres job can. Same shape as the partitioning tests: skip on SQLite rather than assert something SQLite cannot express.
.github/workflows/ci.yml runs five jobs on ubuntu-24.04 (pinned, so a runner
image bump is a deliberate change rather than silent environment drift):
| job | what it does |
|---|---|
test |
unit + cucumber on SQLite |
postgres |
the same suites on Postgres 17, plus schema-shape and INVALID-index assertions |
assets |
precompiles in production (the only path that minifies), boots with a manifest present, asserts the bundle ships jQuery 3 and was minified, and that every emitted asset path exists |
provisioning |
bash -n provision.sh and systemd-analyze verify on the units |
security |
three blocking gates: bundle-audit, brakeman, and gitleaks over the working tree |
A green security job is a snapshot, not a property: ruby-advisory-db moves
under a pinned lock without any code changing, so the gate can go red on its own.
It did — 43 advisories appeared across 11 gems once Rails 8.1.4.1 was published,
cleared by a patch-level bundle update with no Gemfile constraint changed
(rails '~> 8.1.0' already permitted it). Re-run bundle-audit rather than
trusting any count written into the docs.
gitleaks needs a custom rule: the built-in patterns do not flag this project's
actual failure mode, a long hex literal written as
config.secret_key_base = ENV["SECRET_KEY_BASE"] || '<hex>'. .gitleaks.toml
matches that shape and allowlists config/environments/development.rb and
test.rb by path, since those two committed values are not secrets.
Charts run on Chart.js 4.4.7 (MIT), vendored at
vendor/assets/javascripts/chartjs/chart.umd.js. It replaced a vendored Highcharts
4.0.4 build that was an unlicensed commercial dependency. Chart.js lacks Highcharts'
plotBands/plotLines and gauge series, so those live as plugins in
app/assets/javascripts/dad_charts.js (dadBands, dadGauge, dad_enable_x_zoom).
Uglifier was replaced by terser, because UglifyJS 2.x is ES5-only and aborts on
Chart.js's ES2015 output.
Read the comments in app/models/event_ingestor.rb and lib/log_queue.rb. The
checkpoint and the batch flush are coupled, and getting the ordering wrong either
loses rows or duplicates them. Ingest tests drain the queue (flush_and_wait)
between staging steps so exactly one writer is active — that is what makes them
deterministic on SQLite instead of racing SQLite3::BusyException.
- Ruby 3.3.8, Bundler 2.6.7, Rails 8.1.4.1. The upgrade path was 4.2 → 5.2 → 6.1
→ 7.1 → 7.2 → 8.0 → 8.1.4 (tag
rails-8.1.4), one commit per minor step; the lock now sits on the 8.1.4.1 patch release. -
minitest ~> 5.25is load-bearing and easy to "clean up" by mistake: minitest 6 narrowedMinitest::Test.run, and railties' TestUnit runner still calls it with three arguments. -
rspec-railsis required even though there is nospec/directory: cucumber-rails only mixesRSpec::MatchersintoCucumber::Rails::Worldwhenrspec/rails/matchersis loadable, and the step definitions callexpect. - The app never calls
config.load_defaults, so noload_defaults-gated Rails default is ever applied here — every behaviour change must be opted into by hand. -
Gemfile.lockanddb/schema.rbare tracked on purpose; do not re-add them to.gitignore.
AGENTS.md in the repo root carries the full set of upgrade landmines and is the
best starting point for anything version-related.