Create a Rails App

Use this when starting a new Rails project. The command examples use PostgreSQL and GitHub.

Verify Ruby and Rails

Check the active Ruby and Rails versions before creating the app. These should come from the Ruby version managed by mise.

ruby -v
rails -v

Install Ruby with mise

Install and activate Ruby with mise if the project needs a newer Ruby version. This is usually a one-time setup step for each Ruby version.

mise use ruby@latest
ruby -v

Install or update Rails

If rails -v shows an older version than expected, install the latest Rails gem for the active Ruby version.

gem install rails
mise reshim
rails -v

mise reshim refreshes command shims so the rails command points at the newly installed gem executable.

Create the Rails app

Create the app with PostgreSQL as the database.

rails new APP_NAME -d postgresql
cd APP_NAME

After entering the app directory, this guide uses bin/rails so commands run through the app’s generated Rails binstub. rails COMMAND often works too, but bin/rails COMMAND avoids version or gem mismatch issues.

Optional rails new flags

Add these flags when creating the app if the project needs a specific frontend, database, or setup style.

rails new APP_NAME -d postgresql -j esbuild -c tailwind

Options marked (default) do not need to be specified when using the standard Rails defaults.

Database

Flag	Use
-d postgresql	Use PostgreSQL as the database.
-d mysql	Use MySQL as the database.
-d sqlite3	(default) Use SQLite as the database.

JavaScript

Flag	Use
-j importmap	(default) Use import maps for JavaScript.
-j esbuild	Use esbuild for JavaScript bundling.
-j rollup	Use Rollup for JavaScript bundling.
-j webpack	Use webpack for JavaScript bundling.

Stylesheets

Flag	Use
-c tailwind	Use Tailwind CSS.
-c bootstrap	Use Bootstrap.
-c bulma	Use Bulma.
-c sass	Use Sass.

Other Utilities

Flag	Use
--api	Create an API-only Rails app.
--skip-test	Skip Rails test files.
--skip-system-test	Skip system test files.
--skip-action-mailer	Skip Action Mailer.
--skip-action-mailbox	Skip Action Mailbox.
--skip-action-text	Skip Action Text.
--skip-active-storage	Skip Active Storage.
--skip-hotwire	Skip Hotwire.
--skip-jbuilder	Skip Jbuilder.
--skip-bundle	Create the app without running bundle install.

Set up Rails credentials

Use Rails credentials for secrets that the app needs now or later, such as database passwords, API keys, and secret_key_base. Use separate encrypted credentials files for development and production. The encrypted files can be committed, but the key files must stay private because they decrypt the credentials.

Set nano as the editor for the current terminal session before editing credentials.

export EDITOR="nano"

Other common editor options:

export EDITOR="vim"
export EDITOR="emacs"
export VISUAL="code --wait"
export VISUAL="subl --wait"

For editors that open a separate window, use a wait flag so Rails waits until you close the file before saving the encrypted credentials.

If Rails says No $VISUAL or $EDITOR to open file in, set the editor and run the credentials command again.

Open the development credentials file. The first run also creates config/credentials/development.key and adds it to .gitignore.

bin/rails credentials:edit --environment development

Add or update local secrets.

database:
  password: DB_PASSWORD
example_service:
  api_key: API_KEY

Open the production credentials file.

bin/rails credentials:edit --environment production

Add or update production secrets. Rails may create secret_key_base automatically when the production credentials file is initialized.

secret_key_base: SECRET_KEY_BASE
database:
  password: PRODUCTION_DATABASE_PASSWORD
example_service:
  api_key: PRODUCTION_API_KEY

Read credential values in app code or configuration with Rails.application.credentials.

Rails.application.credentials.dig(:example_service, :api_key)

Keep these key files somewhere safe, such as a password manager or deployment secret store:

config/credentials/development.key
config/credentials/production.key

The key files are ignored by Git and are required to decrypt the matching credentials files:

config/credentials/development.yml.enc
config/credentials/production.yml.enc

If a key is lost, Rails cannot read that environment’s credentials. For production deploys, store the production key in the host’s secret manager or set it as RAILS_MASTER_KEY.

secret_key_base is different from the credentials key: Rails stores secret_key_base inside credentials and uses it to sign and encrypt application data such as cookies.

To add, update, or delete credentials later, open the file for the environment you want to change.

bin/rails credentials:edit --environment development

bin/rails credentials:edit --environment production

Create the database

This section assumes the app was created with PostgreSQL. For SQLite, MySQL, or another database, use the matching rails new -d flag and follow the Rails database configuration guide for that adapter.

Before creating the database, create a dedicated PostgreSQL role for the app. This keeps the Rails database config independent from your local system username.

Check whether the app role already exists.

sudo -u postgres psql -c "\du"

Only run the command below if the role is missing.

sudo -u postgres createuser --createdb --login --pwprompt APP_NAME

When prompted, enter the same DB_PASSWORD stored in the development credentials.

Then keep Rails’ generated config/database.yml structure and uncomment the username, password, and host settings for development and test.

development:
  <<: *default
  database: APP_NAME_development
  username: APP_NAME
  password: <%= Rails.application.credentials.dig(:database, :password) %>
  host: localhost

test:
  <<: *default
  database: APP_NAME_test
  username: APP_NAME
  password: <%= Rails.application.credentials.dig(:database, :password) %>
  host: localhost

Leave the rest of the generated file in place unless the app needs a custom host, port, production database, or multiple database setup.

If config/database.yml does not set a username, Rails usually connects with your local system username. An error like role "USERNAME" does not exist means PostgreSQL cannot find a matching role. Set an explicit app role in config/database.yml, or create a PostgreSQL role for that username.

Then create the local development and test databases.

bin/rails db:create

Check the app locally

Start the local development process and open the app in the browser.

bin/dev

Make the first commit

Rails initializes Git by default. Add the generated files and commit the app baseline.

git status
git add .
git commit -m "Initial Rails app"

Push main to GitHub

Create an empty GitHub repo first, then add the SSH remote and push main.

git branch -M main
git remote add origin [email protected]:USERNAME/REPO.git
git push -u origin main

Sources

• The Rails Command Line
• Configuring Rails Applications: Configuring a Database
• Securing Rails Applications: Custom Credentials
• PostgreSQL createuser