Bullet Train: a Rails SaaS template where configure rewrites the README

Clone it, do not fork it

The first instruction is the one that trips people up. The README says that if you are building a new application with Bullet Train, you do not want to fork the template repository. You clone it instead:

git clone https://github.com/bullet-train-co/bullet_train.git your_new_project_name
cd your_new_project_name

Forking is reserved for the other case. The contributing section spells out that you should fork the repository on GitHub, copy the SSH path, clone your fork over SSH, and run `bin/setup`. So the same repository serves two roles with opposite workflows: a generator you clone once and keep, and an upstream you fork to send changes back.

The reason cloning is right for an application is visible in the file list. This repository is not a gem, it is a working Rails application with `app/`, `config/`, `db/`, `test/`, a `Gemfile.lock` and a `yarn.lock`. Cloning it gives you a runnable app with its history, and you push your own code into that clone.

Licence is MIT, in an `MIT-LICENSE` file at the root, with a `SECURITY.md` alongside it. That is a genuinely permissive grant and a genuine contrast with Rails admin frameworks, which often ship a custom or commercial licence.

The local stack is three package managers and two services

Dependencies are described as Homebrew packages on macOS: rbenv and ruby-build for the Ruby version, nvm and Yarn for Node, PostgreSQL as the database, and Redis for Action Cable WebSockets and background job queues. The Brewfile at the root is what `brew bundle` consumes.

The setup is not a single command, and the README is candid about why. Homebrew suppresses the follow-up instructions when it installs tools for the first time, so the template documents those steps itself. If Homebrew is installing nvm for the first time you create the directory and add sourcing lines to `~/.zshrc`:

export NVM_DIR="$HOME/.nvm"
[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"
[ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm"

rbenv then reads the Ruby version out of the template's own `.ruby-version` file:

rbenv init
rbenv install `cat .ruby-version`

Two services have to be running before the app boots, and both are per-machine Homebrew services:

brew services start postgresql@14
brew services start redis

Note the version pin on the database. A template that specifies PostgreSQL 14 in its provisioning means a team whose managed database is already on a later major version will meet a mismatch on day one.

The README marks two of these steps as requiring a new shell, which is a small thing that reliably wastes an hour for people who do not read the warning.

bin/configure rewrites the README, which tells you how opinionated this is

The application-level setup is three commands:

bundle install
bin/configure
bin/setup

`bin/configure` is the step with consequences. A line at the bottom of the README says the template's `README.md` will be replaced with `README.example.md` after running it. That is the project substituting your application's name and details for the generic text, and it is a fair signal of the philosophy: the template is meant to become your repository, not sit beside it.

After setup, `bin/dev` boots the app and you open http://localhost:3000. Development process supervision comes from a `Procfile.dev`, and `.overmind.env` at the root is the configuration for overmind, the process manager the README implies you will be running several processes through.

For working on the template itself there is an optional ngrok path. You uncomment `ngrok: ngrok http 3000` in `Procfile.dev` and run `bin/set-ngrok-url` to point `BASE_URL` at a publicly reachable domain, rerunning that script after each ngrok restart because the URL changes. Webhooks and email callbacks generally need this to work at all in development, so it is worth knowing before you hit a confusing failure.

JavaScript is Tailwind, esbuild and Action Cable, versioned in lockstep

The JavaScript side is not minimal. `package.json` pins the Bullet Train packages to an exact version, three of them together:

"@bullet-train/bullet-train": "1.45.1",
"@bullet-train/bullet-train-sortable": "1.45.1",
"@bullet-train/fields": "1.45.1"

Those exact pins match the v1.45.1 release, so the template and its npm packages are released together and are not meant to drift independently. Many listed dependencies use caret ranges: Hotwire Stimulus and turbo-rails, Action Cable and Action Text at 8.1.x, cable_ready, esbuild, postcss with its import, nesting and css-variables plugins, Tailwind at 3.4.x, and trix for rich text.

The build is theme-aware and deliberately split. `yarn build` runs esbuild, `build:css` runs a `bin/link` step then two postcss invocations, and both mailer stylesheets are compiled separately from the application stylesheet. The package.json script for the light theme sets `THEME="light"`, points `NODE_PATH` at `./node_modules`, and runs the `postcss` binary over `app/assets/stylesheets/application.css` with output at `./app/assets/builds/application.light.css` and `--config./postcss.config.js`.

There is also a `heroku-postbuild` script whose entire body is an echo explaining that it exists to stop Heroku running `yarn build` before Ruby and bundler exist. That is the kind of detail that tells you how much history this template has accumulated.

A separate `zapier/` directory at the root and a `@redocly/cli` dependency alongside a `.redocly.yaml` indicate that API documentation and a Zapier integration are part of what you inherit.

Deployment is two buttons with very different prices

Both hosting paths are offered as one-click deploy buttons from the README, and both are costed there. Render provisions production-grade infrastructure at about $30 per month. Heroku does the same at about $140 per month. The Heroku path additionally requires you to complete the remaining steps in the Deploying to Heroku documentation afterwards, which is a fair signal that the button gets you partway.

There is a third path that neither button covers. The `Dockerfile` at the root is explicitly written for production rather than development, with Kamal or a manual build named as the intended driver. The header comments in that file document both halves: a `docker build` with `--build-arg BULLET_TRAIN_VERSION=$(grep -m 1 BULLET_TRAIN_VERSION Gemfile | cut -d '"' -f 2)` reading the version out of your Gemfile, and a `docker run` that maps port 80, passes `RAILS_MASTER_KEY` from `config/master.key`, and names the container `untitled_application`. It builds in two stages, taking a prebuilt build image from ghcr.io keyed on that same `BULLET_TRAIN_VERSION` argument so the heavy gem compilation happens in an image the project maintains, then copying your application code on top.

A `dev.Dockerfile` and a `gitpod.Dockerfile` also exist, so the container story covers local development and cloud IDEs as well.

The maintenance picture is mixed and worth being precise about. The repository is not archived and the last push was on 2026-10-15, but the newest release tags are v1.45.0 on 2026-05-05, v1.45.1 on 2026-05-06 and v1.44.1 on 2026-05-04. Recent commits on the template do not correspond to recent package releases, and a team pinning the npm packages at 1.45.1 is pinning something last cut in May.

Editorial conclusion

Bullet Train suits a team that is starting a subscription product on Rails and wants accounts, billing scaffolding and a local development stack already wired, and that is willing to accept the template's structure rather than design its own. It does not suit a Rails codebase that already exists, since the template is meant to be cloned into a fresh directory and `bin/configure` rewrites the README, nor a team that does not want PostgreSQL, Redis, Hotwire and Tailwind in its stack from day one. Verify first that the bundled `@bullet-train/bullet-train` packages match the template release you clone, that your machine can run the Homebrew bundle plus rbenv, nvm and two background services, and which hosting route you want, since the Render and Heroku buttons are quoted at roughly $30 and $140 per month.

Frequently asked questions

Official sources

1. bullet-train-co/bullet_train on GitHub
2. Issues
3. License: MIT
4. README
5. Releases