Rails Site Engine

Rails Site Engine is a Rails Engine for production-ready brochure/business websites.

Responsibilities

  • Engine (rails_site_engine): layout, section rendering, SEO defaults, contact flow, shared helpers.
  • Host app (client site): runtime shell + config/site_engine.yml + client-owned content files.

Canonical Local Workflow

1) Engine development harness (CI-style)

Use test/dummy only for engine development and tests.

bin/setup
bin/dev

Dummy app URL: http://localhost:3000

2) Real host-app validation (recommended)

Create real client apps under client_projects/.

bin/new_client_project acme-plumbing --site-profile=home-services --trade-specialty=plumbing --business-name="Acme Plumbing"

This command:

  1. Creates client_projects/acme-plumbing.
  2. Generates a minimal Rails host app (PostgreSQL + importmap + Propshaft).
  3. Adds gem "rails_site_engine", path: "../..".
  4. Runs bin/rails generate rails_site_engine:install.
  5. Prunes host boilerplate down to a slim runtime shell and prepares DB.

Profile options:

  • --site-profile: home-services, software-contracting, portfolio
  • --trade-specialty (home-services only): general, plumbing, carpentry, electrician
  • --business-name: brand/business name for starter content
  • --list-site-profiles: prints available profiles and exits

Interactive behavior:

  • If --site-profile is missing in an interactive shell, the script prompts you.
  • If --site-profile is missing in non-interactive mode, the script exits with an actionable error.

Run the generated app:

cd client_projects/acme-plumbing
bin/dev

Move a client project out of client_projects/ into the parent directory when you want to keep it as a standalone app:

bin/move_client_project acme-plumbing

This also rewrites Gemfile to use the engine Git repo (nicho1991/rails_site_engine) after the move. Default rewritten line: gem "rails_site_engine", git: "[email protected]:nicho1991/rails_site_engine.git"

client_projects/ is intentionally ignored by git so you can keep many disposable repro apps. Override the output root with RAILS_SITE_ENGINE_CLIENT_PROJECTS_ROOT=/absolute/path.

Install Generator Contract

bin/rails generate rails_site_engine:install is the single bootstrap step for host apps. It accepts:

  • --site-profile=<concrete-profile>
  • --business-name="Your Business"

Concrete profiles:

  • home-services-general
  • home-services-plumbing
  • home-services-carpentry
  • home-services-electrician
  • software-contracting
  • portfolio

It is idempotent and ensures:

  • site engine host contract (config/site_engine.yml)
  • content scaffolding (content/site.yml, content/pages/*.md, including content/pages/privacy.md)
  • theme scaffolding (config/theme.yml)
  • content contract guide (content/OVERRIDES.md)
  • route setup with LetterOpenerWeb before engine mount in development
  • Action Mailer railtie enablement in config/application.rb for minimal host apps
  • local dev mail preview via letter_opener_web (Gemfile, config/environments/development.rb, /letter_opener route)
  • host bin/dev with PostgreSQL env defaults + Rails server
  • PostgreSQL env defaults in config/database.yml

Upgrade note for apps generated before this Action Mailer bootstrap fix:

  • Re-run bin/rails generate rails_site_engine:install in the host app, or manually uncomment/add require "action_mailer/railtie" in config/application.rb.
  • Restart the Rails server after updating config/application.rb.

Upgrade note for apps generated before local mail preview setup:

  • Re-run bin/rails generate rails_site_engine:install in the host app, then run bundle install.
  • In development, visit /letter_opener to view delivered contact-form emails.

Upgrade note for apps generated before privacy page scaffolding:

  • Re-run bin/rails generate rails_site_engine:install in the host app to backfill content/pages/privacy.md.
  • If your footer privacy link still uses href: "/privacy", update it to page: "privacy" in content/site.yml.

Local Database Defaults

Engine and generated host apps use:

  • POSTGRES_HOST=127.0.0.1
  • POSTGRES_PORT=54325
  • POSTGRES_USER=postgres
  • POSTGRES_PASSWORD=postgres

bin/setup, bin/dev, and bin/new_client_project start Docker Postgres when Docker is available.

Tooling Requirements

  • Node.js >=20 (required only when maintaining engine CSS/tooling locally)

Dependency Knowledge Baselines

Host Content Contract

Each host app must provide:

  • config/site_engine.yml
  • content/site.yml
  • content/pages/<slug>.md
  • config/theme.yml

profile and business_name in config/site_engine.yml are scaffolding inputs for installer-generated files. Runtime rendering reads content from host files (content/site.yml, content/pages/*.md, config/theme.yml).

Updating Client Sites

When engine structure changes:

  1. Update this engine.
  2. In each client app: bundle update rails_site_engine.
  3. Deploy the client app.

Tests

Run engine tests (dummy harness):

bin/rails test

License

MIT. See MIT-LICENSE.