---
url: /getting-started.md
---
# 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:

```sh
rails -v
```

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

Check your Yarn version:

```sh
yarn -v
```

If it's not a 4.x version, or `yarn` isn't found, install it with [corepack](https://github.com/nodejs/corepack). Node 25 and later no longer ship corepack, so install it first:

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

Or, if you manage your tools with [mise](https://mise.jdx.dev):

```sh
mise use --global yarn@4
```

## Create your Rails project

Replace `helloworld` with your own project name:

```sh
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](https://rubygems.org/gems/trek) and the [`trek` npm package](https://www.npmjs.com/package/trek) on npmjs.com (the installer adds the latter to your `package.json`). Install the gem and add it to your `Gemfile`:

```sh
bundle add trek
```

## Run the installer

```sh
bin/rails g trek:install
```

The installer will:

* install all dependencies ([see the full list](/what-is-trek#what-you-get))
* 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](https://postmarkapp.com) credentials, define this ENV variable **before** running the installer so it gets injected into the credentials file automatically:

```sh
export POSTMARK_API_TOKEN=YOUR_TOKEN
```

You can also do it manually afterwards:

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

## Create an admin user

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

```sh
bin/rails g trek:admin:user
```

## Start the server

```sh
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:

```sh
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](/customize) — branding, favicon, components
* [Reference manual](/reference/) — generators, models, components and more
* [Deploying to Scalingo](/deploy) — `trek:scalingo`, a few environment variables, and the dedicated trek-buildpack handles the rest