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 20+
• Yarn 3.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 3.x version, run:

corepack enable
corepack install --global yarn@3

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

Get access to Trek

Trek is distributed as a gem and an NPM package from Etamin Studio's GitLab. Create a deploy token associated to the Trek project:

• Name: your project name (e.g. helloworld)
• Username: your project name (e.g. helloworld)
• Scopes: read_repository, read_package_registry

Export the generated token (replace XXXXXXXXXXX):

export TREK_DEPLOY_TOKEN=XXXXXXXXXXX

Install the gem

Add the deploy token to your project's local Bundler config:

bundle config git.etaminstud.io $TREK_PROJECT_NAME:$TREK_DEPLOY_TOKEN

Install the gem and add it to your Gemfile:

bundle add trek --git https://git.etaminstud.io/etaminstudio/trek.git --branch main

Prepare the NPM package installation:

export NPM_AUTH_TOKEN=$TREK_DEPLOY_TOKEN

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 (Sorcery), 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