Installer

bin/rails g trek:install
# or (soon)
trek install

Trek provides an install generator, that will:

• install all dependencies
• create the User model and include Trek's concerns
• create the Page, PagePath and PageVersion models and include Trek's concerns
• create the Fragment model and include Trek's concerns
• create the relevant policies
• generate and run the relevant migrations

It ends with what to do next: create an admin user, start the server, and the generators it leaves for later, to run as the app needs them: trek:scaffold, trek:taxonomies, trek:audit_log, trek:public_accounts and trek:scalingo.

Sub-generators

The installer orchestrates dedicated sub-generators, all under the trek:install:* namespace. Each one can also be run individually, e.g. bin/rails g trek:install:healthcheck.

Area	What gets set up
Authentication	bcrypt and has_secure_password on User, the User::Session model (one per signed-in browser, found through a signed session_id cookie), the Trek::Authentication controller concern, login/logout & password reset panels
Authorization	ActionPolicy and the base policies
Models	User, Page, PagePath, PageVersion, Fragment, MenuNode, ExternalLink, Current — with migrations
Attachments	Shrine configuration and the uploaders
Emails	Postmark, AdminMailer (invitations, new sign-in and lockout alerts) and Admin::PasswordsMailer (password resets)
I18n	rails-i18n, Mobility, i18n-tasks and the locale files
Admin panels	Pages, fragments, users, sessions, password resets, routes, dashboard, and a Security page for admins
Pagination	Kaminari
Tooling	esbuild, PostCSS, EditorConfig, Procfiles, Makefile, health check endpoint
Linting	RuboCop (rubocop-rails-omakase and rubocop-rspec), ESLint, Stylelint, Prettier, Slim Lint, Lefthook git hooks
Security	Brakeman, bundler-audit, yarn npm audit; HTTPS only (force_ssl, with HSTS), a Content Security Policy and the Permissions-Policy header (trek:install:security_headers) — see Security headers
Jobs	GoodJob as the Active Job backend, replacing Solid Queue — dashboard at /admin/good_job, cron in config/initializers/good_job.rb, pool sized by GOOD_JOB_MAX_THREADS — see Background jobs
Monitoring	AppSignal error tracking and performance monitoring — config/appsignal.rb, the push API key in the credentials, and the AppsignalContext concern tagging transactions per area and user
Specs	RSpec, and specs for what Trek installs (trek:install:model_specs): its models (spec/models/page_spec.rb, spec/models/user_spec.rb…), the admin's requests, policies and mailers, with their test data as Oaken seed scripts — defaults in db/seeds/setup/, scenarios in db/seeds/test/cases/ loaded with seed "cases/…". They check Trek's behaviour in your app — slugs and paths, user validations and roles — so a customization that breaks it fails your suite; edit or remove the ones you deliberately change. Trek's own suite runs the same files
N+1 detection	Prosopite (development/test), scanning every request — see Controllers › N+1 detection
CI	GitLab CI configuration: specs, linters, Brakeman, bundler-audit, yarn npm audit, and, commented out, a Software Bill of Materials

ENV variables read by the installer

Define these before running the installer to have them injected automatically:

• POSTMARK_API_TOKEN — injected into the Rails credentials for email delivery
• APPSIGNAL_PUSH_API_KEY — injected into the Rails credentials for error tracking and performance monitoring

Vulnerable dependencies

make scan and the generated CI check the app's dependencies for known vulnerabilities: the gems of Gemfile.lock with bundler-audit (bundler-audit job), the npm packages of yarn.lock with yarn npm audit (npm-audit job). Like bundler-audit, the npm check fails on any advisory, whatever its severity, and also on a deprecated package, which no longer gets security fixes. It only checks the packages the app bundles (dependencies, with their own): an advisory on a build or lint tool (devDependencies) doesn't block a deploy.

To fix a vulnerable gem, make audit-fix updates it, commits and pushes. For an npm package:

• yarn why <package> shows which dependency brings it in.
• yarn up -R <package> moves it to the latest version its dependents allow; a direct dependency goes to a fixed version with yarn up <package>@<version>.
• When a dependent pins a vulnerable range, a resolutions entry in package.json forces a fixed version, e.g. "resolutions": { "nanoid@^4.0.0": "^5.1.16" }, once you've checked the dependent works with it. Remove it when the dependent catches up.
• A deprecated package is replaced by the one its notice names, or upgraded past the deprecated version.
• An advisory that doesn't apply to the app (code it never reaches), or a deprecation that can't be fixed yet, can be skipped: add its ID to npmAuditIgnoreAdvisories in .yarnrc.yml, with a comment saying why. The ID is the number yarn npm audit shows, or <package> (deprecation) for a deprecation.

Software Bill of Materials

The generated CI has an sbom job, commented out: uncomment it when a client asks for an SBOM, as clients subject to NIS2 may. It lists the gems and npm packages of Gemfile.lock and yarn.lock, with their versions and licenses, in a CycloneDX file, sbom.cdx.json, running cdxgen on every pipeline. GitLab keeps each branch's latest artifacts by default, so the production branch's SBOM can be downloaded from its last pipeline (Build › Artifacts).

Looking up the licenses on RubyGems and npm takes a couple of minutes; set FETCH_LICENSE=false in the job's command to skip it. The command runs with an empty environment (env -i), so cdxgen and the packages npx installs for it can't read the CI's tokens and secret variables.

Trek's own CI makes one for each released version, on its tag, and keeps it for good.