Getting started

This guide takes you from an empty directory to a working Rails application with a Trek back-office.

Prerequisites

Make sure the following are installed:

• Ruby 3.3+
• Rails 8.0 or 8.1: 8.1.4 or later, or add gem "json", "< 3" to the Gemfile, as json 3 needs Rails 8.1.4
• PostgreSQL 12+
• Node 22+
• Yarn 4.x
• libvips

Check your Rails version:

rails -v

If it's older than 8.0, run gem install rails to upgrade.

Check your Yarn version:

yarn -v

If it's not a 4.x version, or yarn isn't found, install it with corepack. Node 25 and later no longer ship corepack, so install it first:

npm install --global corepack
corepack enable
corepack install --global yarn@4

Or, if you manage your tools with mise:

mise use --global yarn@4

Create your Rails project

Replace helloworld with your own project name:

export TREK_PROJECT_NAME=helloworld
rails new $TREK_PROJECT_NAME -j esbuild -d postgresql \
  --skip-action-mailbox --skip-action-text --skip-action-cable \
  --skip-active-storage --skip-jbuilder --skip-test --skip-system-test
cd $TREK_PROJECT_NAME

Install the gem

Trek is distributed publicly: the gem on RubyGems and the trek npm package on npmjs.com (the installer adds the latter to your package.json). Install the gem and add it to your Gemfile:

bundle add trek

Run the installer

bin/rails g trek:install

The installer will:

• install all dependencies (see the full list)
• 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
• set up authentication (has_secure_password with database-backed sessions), authorization (ActionPolicy), uploads (Shrine), emails (Postmark), i18n, linting, CI and more

Configure Postmark (optional)

If you already know your Postmark credentials, define this ENV variable before running the installer so it gets injected into the credentials file automatically:

export POSTMARK_API_TOKEN=YOUR_TOKEN

You can also do it manually afterwards:

EDITOR="code --wait" bin/rails credentials:edit

Create an admin user

Set ADMIN_EMAIL and ADMIN_PASSWORD in your .env, then run:

bin/rails g trek:admin:user

Start the server

bin/dev

Open http://localhost:3000/admin and sign in with your admin credentials. Welcome to your back-office! 🏔

Scaffold your first resource

Trek's scaffold generator creates everything an admin panel needs for a model:

bin/rails g trek:scaffold Book title:string intro:text
bin/rails db:migrate

This generates, in a single command:

• the Book model and migration (calling the Rails model generator behind the scenes), whose to_s, the title the admin shows a book by, returns its title
• the Admin::BooksController based on Trek::ResourceController
• the index, show, new, edit views and form partial
• the Admin::BookPolicy with role-based permissions
• the admin routes
• the locale files
• a menu entry in the admin dashboard

Next steps:

• Customize Trek — branding, favicon, components
• Reference manual — generators, models, components and more
• Deploying to Scalingo — trek:scalingo, a few environment variables, and the dedicated trek-buildpack handles the rest