Rails Superstack

Rails Superstack is a ready-to-go Ruby on Rails instance with front-end, database, and accouterments. A majestic monolith with a f*ckton of useful gems. It's a free public template anyone can use to hit the ground running with their own app ideas.

• Getting Started
  • Prerequisites
  • Run Rename Script
  • Set Up Font Awesome
  • Build and Run
• What's in a Superstack, Exactly?
  • Tech Stack
  • Gems and Resources
  • Code Features
  • Routes
    • User Routes
    • Admin Routes
    • Demo Routes
• Linting, Testing, and CI
  • Linting
  • Testing
  • Local CI
• GraphQL API
  • Getting Auth Tokens
    • In Rails
    • In Terminal
  • Making Queries
• Ephemera
  • Cleanup Script
• Acknowledgements

Getting Started

First things first. Create a repository from this template. It's only two steps!

1. Click on "Use this template" above the file list
2. Select "Create a new repository"

Clone the new repo to your local machine, and you're done! (I suppose that's technically three steps)

Prerequisites

With your shiny new repo in hand, here's what you need to get cooking:

• Bundler 2.7.2
• PostgreSQL 18.1
• Redis 8.4.1
• Ruby 3.4.7
• Typesense 30.1

I'd personally recommend Homebrew and rbenv to install these prerequisites:

cd /path/to/your/repo

# Install Homebrew + Postgres
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install postgresql@18

# Install Redis + Typesense
brew install redis
brew install typesense/tap/typesense-server@30.1

# Install rbenv + Ruby
curl -fsSL https://rbenv.org/install.sh | bash
rbenv install 3.4.7

# Install Bundler
gem install bundler -v 2.7.2

# start up the services
brew services start postgresql@18
brew services start redis
brew services start typesense-server@30.1

Run Rename Script

Unless you want your app to be called "Rails Superstack", you'll probably want to run this script:

cd /path/to/your/repo

# Get help
script/rename.sh --help

# Preview changes
script/rename.sh --dry-run

# Run interactively
script/rename.sh

# Run without prompts
script/rename.sh --no-confirmation

The script should be clever enough to detect your new repo's origin url. If not, it'll prompt you for it. If that fails, it'll prompt for your GitHub username and repository name.

After the script runs successfully, it'll delete itself and create a new README.

Set Up Font Awesome

This one's easy. Navigate to Get Started with Font Awesome to sign up and add a new icon kit. Create an app configuration using the included config/application.yml.example file, then plug in your shiny new kit:

cd /path/to/your/repo
cp config/application.yml.example config/application.yml

Open config/application.yml and replace font_awesome_kit_url with your kit's url.

Build and Run

You can install dependencies, set up the database, run migrations – etc. etc. – or you can live on the wild side and run the setup script:

cd /path/to/your/repo
bin/setup

Done this song-and-dance before? If you just need to start up the development server, you can skip straight to the end and run the dev script:

cd /path/to/your/repo
bin/dev

Open localhost:3000 in your web browser and you're good to go!

What's in a Superstack, Exactly?

Tech Stack

Rails Superstack is installed by default with:

• Ruby on Rails
• Hotwire
• Postgres
• Puma
• RuboCop
• Tailwind

Gems and Resources

Rails Superstack has been preloaded and configured with the following:

• Strong Migrations (catch unsafe migrations)
• LogBench (log viewer)
• RSpec + Factory Bot + Faker (testing)
• Passwordless + CanCanCan (auth, roles)
• Letter Opener + Letter Opener Web (preview emails)
• Pom Component (view components)
• Font Awesome + Gravatar Image Tag Plugin (icons)
• SuperAdmin + Flipper (admin + feature flags)
• Commonmarker (syntax highlighting)
• Resque (background jobs)
• Typesense + Pagy (search + pagination)
• GraphQL (API)
• Noticed (notifications)
• Figaro (app configuration)

Code Features

Feature	Description
Abilities (Roles)	Ability
Models	User
Helpers	Text, web urls, forms, Font Awesome icons
Normalizers	Email addresses
Validators	Email addresses, web urls
View Components	Clipboard, flash alerts, code snippets

Routes

User Routes

Endpoint	Description
/sign_in	Sign in as a new user
/sign_out	Sign out the current user
/profile	Set current user email
/sent_mail	Preview sent mail (login codes)

Admin Routes

Endpoint	Description
/admin	SuperAdmin dashboard
/flipper	Flipper feature flags
/resque	Resque jobs

Demo Routes

(The cleanup script will remove these endpoints)

Endpoint	Description
/demo/welcome	Starter page with helpful links
/demo/alert	Example for flash alerts
/demo/notice	Example for flash notices
/demo/mac_guffins	Items accessible by current user
/demo/secrets	A "secret" route behind a feature flag
/demo/terminal	Lists useful terminal commands

Linting, Testing, and CI

There's handy binstubs for RSpec and RuboCop. Local CI will mirror the GitHub workflow that runs when you make commits and merge pull requests.

Linting

cd /path/to/your/repo

# Lint code for consistent style
bin/rubocop

Testing

cd /path/to/your/repo

# Run RSpec tests
bin/rspec

Local CI

cd /path/to/your/repo
bin/ci

GraphQL API

GraphQL is a touch different than your vanilla JSON API. The data structures are effectively dynamic, so you can hit a single endpoint to request any sort of data in any sort of order.

An endpoint covers a single GraphQL schema, which could compromise an individual model or literally your entire database. For simplicity and clarify, this repo has three schemas: one for the unauthenticated health check, one for users, and a demo one for MacGuffins.

Learn more about GraphQL

Getting Auth Tokens

The API uses token-based authentication. You'll need a bearer authentication token to make queries to authenticated endpoints.

In Rails

You can use ApiToken.issue!(user:, name:) to get a bearer auth token in Rails. Pass in current_user to query resources available in the current session.

In Terminal

There's a one-stop binstub to pipe a bearer auth token directly into your GraphQL queries:

cd /path/to/your/repo

# Returns "Bearer TOKEN" for direct usage
bin/api-token api@superstack.dev

Making Queries

To query data in GraphQL, you POST to an endpoint with your query as the payload. The examples below use curl to hit the API and pipe the responses to jq for pretty formatting in the terminal.

cd /path/to/your/repo

# health check
curl -s -H 'Content-Type: application/json' \
  -X POST http://localhost:3000/graphql/health \
  -d '{"query":"{ apiHealth { status } }"}' | jq

# users
# requires authentication
bin/api-token | xargs -I% curl -s -H 'Content-Type: application/json' \
  -H 'Authorization: %' \
  -X POST http://localhost:3000/graphql \
  -d '{"query":"{ users { id email role } }"}' | jq

# MacGuffins
# requires authentication
bin/api-token | xargs -I% curl -s -H 'Content-Type: application/json' \
  -H 'Authorization: %' \
  -X POST http://localhost:3000/demo/graphql \
  -d '{"query":"{ macGuffins { id name description } }"}' | jq

A response will be nicely formatted JSON data:

# POST /graphql/health
{
  "data": {
    "apiHealth": {
      "status": "ok"
    }
  }
}

Ephemera

Cleanup Script

Dislike the demo code with a passion? Easy! Burn it with 🔥 fire 🔥 by running the cleanup script:

cd /path/to/your/repo

# Get help
script/cleanup.sh --help

# Preview changes
script/cleanup.sh --dry-run

# Run interactively
script/cleanup.sh

# Run without prompts
script/cleanup.sh --no-confirmation

The script removes all trace of demo code and database artifacts: assets, controllers, models, views, routes, seeds, factories, specs, and demo migrations.

Cleanup also replaces migration history with a single non-demo baseline and regenerates the schema by dropping and recreating the local database.

After the script runs successfully, it deletes itself and you’ll be left with a pristine Superstack template.

Acknowledgements

The Rails Superstack logo was crafted from an illustration by Muhammad Afandi on Unsplash.