Trek

Trek is a modern content management system for Ruby on Rails, that is designed to get you started fast with useful conventions, then let you customize the back-office to your project's needs.

Prerequisites

  • Rails 7.0+
  • Ruby 3.1+
  • PostgreSQL 12+
  • Node 20+
  • Yarn 3.x
  • libvips

Dependencies

Trek uses these gems under the hood:

You don't have to set them up yourself, but you can customize their configuration once Trek is installed.

Installation

Prerequisites

Make sure your default Rails version is 7.0+

$ rails -v
Rails 7.1.3

If not, run gem install rails to upgrade.

Make sure your default Yarn version is 3.x

$ yarn -v
3.8.0

If not, 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

Create a deploy token associated to Trek project:

  • Name: helloworld (replace with your project name)
  • Username: helloworld (replace with your project name)
  • Scopes: read_repository, read_package_registry

Copy the generated token to an ENV variable (replace XXXXXXXXXXX with the token generated by Gitlab):

export TREK_DEPLOY_TOKEN=XXXXXXXXXXX

Install the gem

Add this deploy token to your project local config:

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

Install the gem and add it to the application's Gemfile by running:

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

Install the NPM package

Prepare the NPM package installation by running:

export NPM_AUTH_TOKEN=$TREK_DEPLOY_TOKEN

Run the installer

Now you're ready to install Trek. This will:

  • install all dependencies
  • create the User model and include Trek's concerns
  • create the Page, PagePath and PageVersion model and include Trek's concerns
  • create the Fragment model and include Trek's concerns
  • create the relevant policies
  • generate and run the relevant migrations

Run:

rails g trek:install

Configure Postmark

If you already know your Postmark credentials, you can define the following ENV variables, prior to running the installer:

export POSTMARK_API_TOKEN=YOUR_TOKEN

This way, they will be injected automatically in the credentials file.

You can also do it manually after running the installer by running:

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

Configure Deepl

DeepL can be use to translate locale files automatically when running the scaffold generator.

To use this feature, specify your DeepL credentials by defining the following ENV variables, prior to running the installer:

export DEEPL_AUTH_KEY=YOUR_TOKEN

If the ENV variable is not found, translations won't happen automatically and you will have to manually edit each locale file (except English).

Usage

Customize branding

Add the favicon:

  • in SVG format at app/assets/images/favicon.svg
  • in PNG format (512 x 512 px) at public/favicon.png

Change the brand title and subtitle

The title and subtitle are customizable in the locales, with the following keys:

en:
  admin:
    brand:
        title: My project
        subtitle: Back-office

Useful commands

Create an admin user

Customize the credentials with ADMIN_EMAIL and ADMIN_PASSWORD ENV variables in .env

rails g trek:admin:user

CI setup

Gitlab

Once your project is created on Gitlab, go to Settings > CI/CD > Variables > Add variable and use these values:

  • Key: BUNDLE_GIT__ETAMINSTUD__IO

  • Value: helloworld:YOUR_DEPLOY_TOKEN (replace with your project name)

  • Key: NPM_AUTH_TOKEN

  • Value: YOUR_DEPLOY_TOKEN

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Testing in a local Rails project

First, follow the Installation instructions above.

Then, configure the project to use the local version of Trek (both the gem and the NPM package).

Linking to the local gem with bundler

Let's use Bundler local feature.

First, make sure you're pointing to Trek's git repo main branch in your Gemfile:

gem "trek", git: "git@git.etaminstud.io:etaminstudio/trek.git", branch: :main

Navigate to your project, then configure the local version of Trek:

cd /local/path/to/yourproject
bundle config set --local local.trek ~/projects/trek

Install the gem and restart the Rails server:

bundle
overmind restart # if you're using overmind

Then, whenever you change the files in Trek, you'll have to restart the Rails server.

When you're done, disable the local version:

bundle config unset --local local.trek

Don't forget to revert to a released verion in your Gemfile:

gem "trek", "~> 0.1"

Linking to the local NPM package with Yarn

Let's use Yarn link feature.

yarn link ~/projects/trek

You don't need to restart the server when you change CSS or JS files in Trek.

When you're done, disable the local package:

yarn unlink ~/projects/trek

Working on documentation

The docs, based on VitePress, are embedded in the /docs folder.

  • Launch dev mode: yarn docs:dev
  • Build the docs: yarn docs:build
  • Open the built docs: yarn docs:preview

Publishing a new version

make release

This will:

  1. Prompt for the new version number (showing the current version)
  2. Update the version in lib/trek/version.rb and package.json
  3. Run bundle to update the lockfile
  4. Commit all changes with message "Version X.Y.Z"
  5. Run bundle exec rake release (creates git tag, pushes commits/tag, pushes gem to rubygems.org)
  6. Run yarn npm publish (publishes the npm package). This requires a personal token with the api scope to be present in NPM_AUTH_TOKEN,