Installation Guide
System Requirements
Rails Blueprint requires a Unix-like operating system (macOS, Linux, WSL2 on Windows).
| Component | Minimum Version | Recommended Version | Notes |
|---|---|---|---|
| Ruby | 3.2.0 | 3.3.0+ | With YJIT and jemalloc for optimal performance |
| Rails | 7.1.0 | 7.2.2+ | Latest stable version recommended |
| PostgreSQL | 13 | 15+ | Required for primary database |
| Redis | 6.0 | 7.0+ | Used for caching and ActionCable |
| Node.js | 16 | 18+ LTS | For JavaScript compilation |
| Yarn | 1.22 | 1.22+ | Package manager for JavaScript |
Note: For production deployments, we recommend using the latest stable versions of all components.
Ruby Installation
We recommend using a Ruby version manager for easy switching between Ruby versions.
Installing with rbenv (Recommended)
macOS with Homebrew
# Install rbenv and ruby-build
$ brew install rbenv ruby-build
# Set up rbenv in your shell
$ echo 'eval "$(rbenv init -)"' >> ~/.zshrc
$ source ~/.zshrc
# Install Ruby with YJIT and jemalloc
$ RUBY_CONFIGURE_OPTS="--enable-yjit --with-jemalloc" rbenv install 3.3.0
$ rbenv global 3.3.0 Ubuntu/Debian
# Install dependencies
$ sudo apt-get update
$ sudo apt-get install -y build-essential libssl-dev libreadline-dev zlib1g-dev
# Install rbenv
$ git clone https://github.com/rbenv/rbenv.git ~/.rbenv
$ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
$ echo 'eval "$(rbenv init -)"' >> ~/.bashrc
$ source ~/.bashrc
# Install ruby-build
$ git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
# Install Ruby
$ rbenv install 3.3.0
$ rbenv global 3.3.0 Installing with RVM
# Install RVM
$ \curl -sSL https://get.rvm.io | bash -s stable
$ source ~/.rvm/scripts/rvm
# Install Ruby
$ rvm install 3.3.0
$ rvm use 3.3.0 --default Performance Tip: Enable YJIT for better performance by adding
export RUBY_YJIT_ENABLE=1 to your shell configuration.PostgreSQL Setup
macOS Installation
# Install PostgreSQL
$ brew install postgresql@15
$ brew services start postgresql@15
# Create a database user
$ createuser -s postgres Ubuntu/Debian Installation
# Install PostgreSQL
$ sudo apt-get install postgresql postgresql-contrib libpq-dev
# Start PostgreSQL
$ sudo systemctl start postgresql
$ sudo systemctl enable postgresql
# Create a database user
$ sudo -u postgres createuser -s $USER Docker Installation
# Run PostgreSQL in Docker
$ docker run --name rails-blueprint-postgres \
-e POSTGRES_PASSWORD=password \
-p 5432:5432 \
-d postgres:15 Redis Setup
macOS
$ brew install redis
$ brew services start redis Ubuntu/Debian
$ sudo apt-get install redis-server
$ sudo systemctl start redis
$ sudo systemctl enable redis Installation Options
The basic installation includes all essential features:
$ git clone https://github.com/railsblueprint/basic.git myapp
$ cd myapp
$ bundle install
$ rails blueprint:init
$ yarn install
$ rails db:create
$ rails db:migrate:with_data
$ rails db:seed
$ bin/dev For production deployments with Mina. rails blueprint:init renders config/deploy.rb from config/deploy.rb.template, along with config/deploy/staging.rb and config/deploy/production.rb; there is no file to copy by hand.
# Generate config/deploy.rb from config/deploy.rb.template (skip if already initialised)
$ rails blueprint:init
# Edit config/deploy.rb and config/deploy/production.rb with your server details
# Setup server
$ mina production setup
$ mina production deploy Troubleshooting Installation
Common Issues and Solutions
Bundle install fails with native extensions
Install development tools:
# macOS
$ xcode-select --install
# Ubuntu/Debian
$ sudo apt-get install build-essential PostgreSQL connection refused
Ensure PostgreSQL is running:
# Check status
$ pg_isready
# Start PostgreSQL
$ brew services start postgresql # macOS
$ sudo systemctl start postgresql # Linux JavaScript dependencies fail to install
Clear cache and reinstall:
$ rm -rf node_modules yarn.lock
$ yarn install --check-files Still having issues? Check our Troubleshooting Guide or contact support.