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.1+
• Rails 7.0+
• PostgreSQL 12+
• Node 22+
• Yarn 4.x
• libvips

Check your Rails version:

rails -v

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

Check your Yarn version:

yarn -v

If it's not a 4.x version, run:

corepack enable
corepack install --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

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

Configure DeepL (optional)

DeepL is used to translate locale files automatically when running the scaffold generator. To enable it, define this ENV variable before running the installer:

export DEEPL_AUTH_KEY=YOUR_TOKEN

Without it, translations won't happen automatically and you will have to edit each non-English locale file by hand.

Create an admin user

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

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:

rails g trek:scaffold Book title:string intro:text

This generates, in a single command:

• the Book model and migration (calling the Rails model generator behind the scenes)
• 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 (auto-translated via DeepL if configured)
• 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:install:scalingo, a few environment variables, and the dedicated trek-buildpack handles the rest