Getting Started with Ruby on Rails API ​

This quickstart launches a Ruby on Rails API to AWS via Nullstone. It also configures a local development environment using Docker that works identical to production, but with debugging enabled.

This quickstart contains a walkthrough for generating a Rails app. A working example is available to fork at nullstone-io/rails6-api-quickstart.

Create Rails app ​

Generate app ​

In this example, we are going to create a rails API in the current directory. In your repository root, run this command.

rails new --database=postgresql --api .

rails new --database=postgresql --api .

This will create the following files and directories:

.
├── app
├── bin
├── config
├── db
├── lib
├── log
├── public
├── storage
├── tmp
├── vendor
├── config.ru
├── Gemfile
├── Gemfile.lock
└── Rakefile

.
├── app
├── bin
├── config
├── db
├── lib
├── log
├── public
├── storage
├── tmp
├── vendor
├── config.ru
├── Gemfile
├── Gemfile.lock
└── Rakefile

Configure Datastores ​

A Rails app is not very interesting without a database. In this section, you will configure additional datastores.

Postgresql ​

In order for your Rails app to connect to postgresql, you need to change the postgresql configuration.

1. Open config/database.yml and update the default section to use DB_ADAPTER and DATABASE_URL environment variables.

default: &default
  adapter: <%= ENV.fetch("DB_ADAPTER") { 'postgresql' } %>
  encoding: unicode
  # For details on connection pooling, see Rails configuration guide
  # https://guides.rubyonrails.org/configuring.html#database-pooling
  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
  url: <%= ENV['DATABASE_URL'] %>

default: &default
  adapter: <%= ENV.fetch("DB_ADAPTER") { 'postgresql' } %>
  encoding: unicode
  # For details on connection pooling, see Rails configuration guide
  # https://guides.rubyonrails.org/configuring.html#database-pooling
  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
  url: <%= ENV['DATABASE_URL'] %>

2. Keep config/database.yml open and change the production section to use all default settings.

production:
  <<: *default
#  database: rails6_webapp_quickstart_production
#  username: rails6_webapp_quickstart
#  password: <%= ENV['RAILS6_WEBAPP_QUICKSTART_DATABASE_PASSWORD'] %>

production:
  <<: *default
#  database: rails6_webapp_quickstart_production
#  username: rails6_webapp_quickstart
#  password: <%= ENV['RAILS6_WEBAPP_QUICKSTART_DATABASE_PASSWORD'] %>

Prepare for Local ​

Configure logging ​

When running apps in a container, it's recommended that you emit logs to stdout. To set this up, we're going to log to stdout if RAILS_LOG_TO_STDOUT environment variable is present.

The nullstone/rails images set this environment variable. By default, the Rails production environment handles this, but the development environment does not.

To configure, open ./config/environments/development.rb and add the following anywhere inside the configuration block.

# Tell Active Support which deprecation messages to disallow.
config.active_support.disallowed_deprecation_warnings = []

# Use default logging formatter so that PID and timestamp are not suppressed.
config.log_formatter = ::Logger::Formatter.new

if ENV["RAILS_LOG_TO_STDOUT"].present?
   logger           = ActiveSupport::Logger.new(STDOUT)
   logger.formatter = config.log_formatter
   config.logger     = ActiveSupport::TaggedLogging.new(logger)
end

# Raise an error on page load if there are pending migrations.
config.active_record.migration_error = :page_load

# Tell Active Support which deprecation messages to disallow.
config.active_support.disallowed_deprecation_warnings = []

# Use default logging formatter so that PID and timestamp are not suppressed.
config.log_formatter = ::Logger::Formatter.new

if ENV["RAILS_LOG_TO_STDOUT"].present?
   logger           = ActiveSupport::Logger.new(STDOUT)
   logger.formatter = config.log_formatter
   config.logger     = ActiveSupport::TaggedLogging.new(logger)
end

# Raise an error on page load if there are pending migrations.
config.active_record.migration_error = :page_load

Configure docker locally ​

Now, create a docker-compose.yml to run locally using Docker with an attached postgres Docker container.

version: "3.8"

services:
   app:
      image: nullstone/rails:local
      volumes:
         - .:/app
         - gems:/usr/local/bundle
      ports:
         - "9000:80"
      environment:
         - NULLSTONE_ENV=local
         - POSTGRES_URL=postgres://postgres:postgres@db:5432/app
      depends_on:
         - db

   db:
      image: "postgres:13"
      ports:
         - "5432:5432"
      environment:
         - POSTGRES_USER=postgres
         - POSTGRES_PASSWORD=postgres
         - POSTGRES_DB=app

volumes:
   gems: {}

version: "3.8"

services:
   app:
      image: nullstone/rails:local
      volumes:
         - .:/app
         - gems:/usr/local/bundle
      ports:
         - "9000:80"
      environment:
         - NULLSTONE_ENV=local
         - POSTGRES_URL=postgres://postgres:postgres@db:5432/app
      depends_on:
         - db

   db:
      image: "postgres:13"
      ports:
         - "5432:5432"
      environment:
         - POSTGRES_USER=postgres
         - POSTGRES_PASSWORD=postgres
         - POSTGRES_DB=app

volumes:
   gems: {}

Let's start our app locally.

docker compose up

docker compose up

Visit http://localhost:9000.

Update dependencies ​

As you add dependencies to your application, ensure that there is an entry for the dependency in Gemfile. Then, restart your docker container with docker compose up or docker compose restart. The local docker image will install dependencies on boot.

Prepare for Production ​

Before deploying a Rails app to production, we need to dockerize the app. In this section, we will create a simple Dockerfile.

Create Dockerfile ​

# syntax=docker/dockerfile:1
FROM nullstone/rails

ENV RAILS_ENV production

# Install packages
COPY Gemfile* .
RUN gem install bundler
RUN bundle install

# Copy in code
COPY . .

# syntax=docker/dockerfile:1
FROM nullstone/rails

ENV RAILS_ENV production

# Install packages
COPY Gemfile* .
RUN gem install bundler
RUN bundle install

# Copy in code
COPY . .

Launch to Nullstone ​

Create app ​

When launching to Nullstone, we're going to create an app in the Nullstone UI and attach capabilities that automatically configure our app. Follow these steps in the Nullstone UI.

1. Create an application.
   • Name: In this example, we're naming our app rails-api-quickstart
   • Framework: rails
   • App Type: Container
2. From the Domains tab for the application, add a subdomain. (This will automatically attach a load balancer capability)
3. From the Capabilities tab for the application, add a capability named SECRET_KEY for Rails Cookies.

Create postgresql datastore ​

1. Create a datastore - RDS Postgres Cluster
2. Visit your application created in the previous step.
3. From the Datastores tab, add the datastore you just created.

Provision ​

Our application is ready to launch. Click "Launch" through the UI or issue up through the CLI.

nullstone up --wait --app=rails-api-quickstart --env=dev

nullstone up --wait --app=rails-api-quickstart --env=dev

Build ​

Once your application is provisioned, you may build and deploy your app.

You can name your image whatever you want, just remember this image name for the deploy step. In this example, we are using an image name of rails-api.

docker build -t rails-api .

docker build -t rails-api .

Deploy ​

Now, issue launch to push your docker image and deploy the service with a new version.

nullstone launch --source=rails-api --app=rails-api-quickstart --env=dev

nullstone launch --source=rails-api --app=rails-api-quickstart --env=dev

Troubleshooting ​

Auto-versioning ​

When pushing your image, Nullstone performs auto-versioning if you are in a git-tracked directory. Nullstone selects the short commit SHA (a unique 8-character token) from the git repository to tag the docker image.

To use a manual version, issue launch with --version (this example uses 1.0.0).

nullstone launch --source=rails-api --app=rails-api-quickstart --env=dev --version=1.0.0

nullstone launch --source=rails-api --app=rails-api-quickstart --env=dev --version=1.0.0

Version conflicts ​

Nullstone enforces version/image tag immutability for security reasons.

If you repeatedly push a new docker image without committing anything to git, you will receive an error message like this:

error pushing artifact: error pushing image: tag invalid: The image tag 'c3c7cd83' already exists in the 'periwinkle-louse-fkslv' repository and cannot be overwritten because the repository is immutable.

error pushing artifact: error pushing image: tag invalid: The image tag 'c3c7cd83' already exists in the 'periwinkle-louse-fkslv' repository and cannot be overwritten because the repository is immutable.

The easiest way to resolve this is to launch with an indexed version. The following uses the same commit sha, but with a -2 suffix to distinguish the image tag.

nullstone launch --source=rails-api --app=rails-api-quickstart --env=dev --version=c3c7cd83-2

nullstone launch --source=rails-api --app=rails-api-quickstart --env=dev --version=c3c7cd83-2