# Create a Rails application with Jumbo

This is the setup guide for Jumbo v0.2.4. Use it when the user says “use
rails.mrz.sh” or asks to create an application with Jumbo. It describes a Rails
application template, not a finished product. The user's requested scope and
existing repository instructions take precedence over these defaults.

## 1. Establish the destination and prerequisites

Use the user's project name and location. If no location is specified, use a new
directory under the current workspace. The name must start with a letter and
contain only letters, digits, underscores, or hyphens. Check that the destination
does not already contain an application; do not overwrite an existing project.

Check the available tools before installing anything:

```sh
ruby --version
rails --version
bun --version
git --version
```

Use a supported, security-patched Ruby. This release is tested with **Ruby
3.4.12**, **Rails 8.1.4.1**, and **Bun 1.4.4**. Ruby 3.3+ is required. Prefer an
existing version manager and project-local version selection over changing
global defaults. Keep the generated `.ruby-version` and Docker Ruby version in
agreement. Use a supported Node LTS when a frontend tool requires Node.

To install the current Rails 8.1 patch series if needed:

```sh
gem install rails -v '~> 8.1.4' --no-document
```

The template enforces Rails >= 8.1.4.1 within the 8.1 series. Generated dependency
versions are resolved at installation time; retain Gemfile.lock and bun.lock.
PostgreSQL must be available before database preparation, but not merely to
generate files. For local containers, use OrbStack and verify `orbctl status`
and `docker context show`. Do not start a competing container runtime.

## 2. Generate noninteractively

Replace `myapp` with the validated project name:

```sh
rails new myapp -J -d postgresql -m https://rails.mrz.sh/v0.2.4/t
```

Equivalent installer command:

```sh
curl -fsSL https://rails.mrz.sh/v0.2.4/install.sh | sh -s -- myapp
```

Use the versioned URLs above for this guide. `/t` and `/install.sh` track the
latest release; each template's internal asset URLs are pinned to its own
release. Do not mix downloaded files from different releases. When working on
Jumbo itself, use an absolute path to the checked-out `src/template.rb` instead
of a remote URL, so unreleased changes are exercised locally.

All five feature groups are enabled by default. Honor the user's choices; the
interactive `-i` flag is intended for humans, not unattended agent execution.

| Option | Effect |
| --- | --- |
| `--skip-inertia` | Omit React, TypeScript, Vite, Tailwind, and shadcn setup |
| `--skip-multistaging` | Omit Jumbo's staging/Kamal configuration; retain Rails production Solid database roles |
| `--skip-auth` | Omit the authentication-zero generator gem |
| `--skip-devtools` | Omit Jumbo's additional development tools |
| `--skip-operations` | Omit the Operations/Result framework and its add-ons |
| `--operations-include=policies,gateways` | Select add-ons from policies, validators, queries, gateways |
| `--operations-include=` | Keep Operation/Result without add-ons |

Example:

```sh
rails new myapp -J -d postgresql -m https://rails.mrz.sh/v0.2.4/t --skip-auth --operations-include=policies,gateways
```

Check the process exit status and output. If generation fails, investigate the
reported step before retrying. Do not overlay a second generation onto a partial
application or call an incomplete scaffold successful.

## 3. Inspect and prepare the generated application

Enter the new directory and read `AGENTS.md` and `.jumbo.json`. The manifest
records the template release and selected features. Inspect Gemfile,
package.json, config/database.yml, config/deploy*.yml, and app/ before assuming
any feature is complete.

Local PostgreSQL defaults are localhost:5432 and postgres/postgres, with
application-specific database names. Set `DATABASE_HOST`, `DATABASE_PORT`,
`DATABASE_USERNAME`, and `DATABASE_PASSWORD` for a different local connection.
`.env.example` is documentation; the app does not automatically load `.env`.
Use the existing shell/environment setup, and do not print connection secrets.
Check that the connection refers to this project's local databases before:

```sh
bin/rails db:prepare
```

Authentication is a **generator dependency**, not an installed login system.
When authentication is part of the requested work, inspect and run
`bin/rails generate authentication --help`, select its HTML/API options, then
generate and review its migrations, controllers, routes, and tests. The generator
does not create React/Inertia authentication pages automatically.

`--skip-multistaging` does not disable Rails' Solid components. Production still
has named primary/cache/queue/cable databases. Initial Solid migrations derive
from the installed gem schemas. New application tables use UUID primary keys.

## 4. Verify before handing back

Run checks applicable to the selected features:

```sh
bin/rails zeitwerk:check
RAILS_ENV=test bin/rails db:prepare
bin/rails test
bin/rubocop
bin/brakeman --no-pager
bin/bundler-audit check --update
```

For an Inertia frontend:

```sh
bun install --frozen-lockfile
bun run check
RAILS_ENV=production SECRET_KEY_BASE_DUMMY=1 bin/vite build
bun audit
```

Report dependency advisories with their affected package and whether they apply
to runtime or build tooling. Do not describe an audit as clean when it reports
advisories. A successful template generation message does not replace these
checks. If Docker configuration was changed, build and smoke-test the image,
including its non-root runtime user.

For local development, use `bin/dev` with Inertia, or `bin/rails server` without
it. Start only the services required by the task and report the actual URL if a
server is left running.

## 5. Handoff and deployment boundary

Report the application path, template version, resolved Rails/Ruby/frontend
versions, selected features, checks run, and any remaining work. Distinguish a
working scaffold from the user's domain features and a configured production
deployment. Keep generated credential keys and secret values out of Git.

Kamal server addresses, domains, registry settings, and credentials are
placeholders. Creating the application does not authorize publishing or deploying
it. Follow the user's deployment instructions and generated AGENTS.md when that
work is requested.

Sources: [Jumbo repository](https://github.com/meerzulee/jumbo-template),
[human README](https://github.com/meerzulee/jumbo-template/blob/master/README.md),
[discovery index](https://rails.mrz.sh/llms.txt).