# Using the Elastic Beanstalk Ruby platform
The Ruby platform

This topic describes how to configure, build, and run your Ruby applications on Elastic Beanstalk.

AWS Elastic Beanstalk supports a number of platform branches for different versions of the Ruby programming language. See [Ruby](https://docs.aws.amazon.com/elasticbeanstalk/latest/platforms/platforms-supported.html#platforms-supported.ruby) in the *AWS Elastic Beanstalk Platforms* document for a full list.

The Ruby web application can run behind an NGINX proxy server under a Puma application server. If you use RubyGems, you can include a [`Gemfile`](ruby-platform-gemfile.md) in your source bundle to install packages during deployment.

**Application server configuration**  
Elastic Beanstalk installs the Puma application server based on the Ruby platform branch that you choose when you create your environment. For more information about the components provided with the Ruby platform versions, see [Supported Platforms](https://docs.aws.amazon.com/elasticbeanstalk/latest/platforms/platforms-supported.html#platforms-supported.ruby) in the *AWS Elastic Beanstalk Platforms* guide.

You can configure your application with your own provided Puma server. This provides the option to use a version of Puma other than the one pre-installed with the Ruby platform branch. You can also configure your application to use a different application server, such as Passenger. To do so, you must include and customize a `Gemfile` in your deployment. You're also required to configure a `Procfile` to start the application server. For more information see *[Configuring the application process with a Procfile](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/ruby-platform-procfile.html)**.*

**Other configuration options**  
Elastic Beanstalk provides [configuration options](command-options.md) that you can use to customize the software that runs on the Amazon Elastic Compute Cloud (Amazon EC2) instances in your Elastic Beanstalk environment. You can configure environment variables needed by your application, enable log rotation to Amazon S3, and map folders in your application source that contain static files to paths served by the proxy server. The platform also predefines some common environment variables related to Rails and Rack for ease of discovery and use.

Configuration options are available in the Elastic Beanstalk console for [modifying the configuration of a running environment](environment-configuration-methods-after.md). To avoid losing your environment's configuration when you terminate it, you can use [saved configurations](environment-configuration-savedconfig.md) to save your settings and later apply them to another environment.

To save settings in your source code, you can include [configuration files](ebextensions.md). Settings in configuration files are applied every time you create an environment or deploy your application. You can also use configuration files to install packages, run scripts, and perform other instance customization operations during deployments.

Settings applied in the Elastic Beanstalk console override the same settings in configuration files, if they exist. This lets you have default settings in configuration files, and override them with environment-specific settings in the console. For more information about precedence, and other methods of changing settings, see [Configuration options](command-options.md).

For details about the various ways you can extend an Elastic Beanstalk Linux-based platform, see [Extending Elastic Beanstalk Linux platforms](platforms-linux-extend.md).

## Configuring your Ruby environment


You can use the Elastic Beanstalk console to enable log rotation to Amazon S3 and configure variables that your application can read from the environment.

**To access the software configuration settings for your environment**

1. Open the [Elastic Beanstalk console](https://console.aws.amazon.com/elasticbeanstalk), and in the **Regions** list, select your AWS Region.

1. In the navigation pane, choose **Environments**, and then choose the name of your environment from the list.

1. In the navigation pane, choose **Configuration**.

1. In the **Updates, monitoring, and logging** configuration category, choose **Edit**.

### Log options


The **Log options** section has two settings:
+ **Instance profile**– Specifies the instance profile that has permission to access the Amazon S3 bucket associated with your application.
+ **Enable log file rotation to Amazon S3** – Specifies whether log files for your application's Amazon EC2 instances are copied to the Amazon S3 bucket associated with your application.

### Static files


To improve performance, you can use the **Static files** section to configure the proxy server to serve static files (for example, HTML or images) from a set of directories inside your web application. For each directory, you set the virtual path to directory mapping. When the proxy server receives a request for a file under the specified path, it serves the file directly instead of routing the request to your application.

For details about configuring static files using configuration files or the Elastic Beanstalk console, see [Serving static files](environment-cfg-staticfiles.md).

By default, the proxy server in a Ruby environment is configured to serve static files as follows:
+ Files in the `public` folder are served from the `/public` path and the domain root (`/` path).
+ Files in the `public/assets` subfolder are served from the `/assets` path.

The following examples illustrate how the default configuration works:
+ If your application source contains a file named `logo.png` in a folder named `public`, the proxy server serves it to users from `subdomain.elasticbeanstalk.com/public/logo.png` and `subdomain.elasticbeanstalk.com/logo.png`.
+ If your application source contains a file named `logo.png` in a folder named `assets` inside the `public` folder, the proxy server serves it from `subdomain.elasticbeanstalk.com/assets/logo.png`.

You can configure additional mappings for static files. For more information, see [Ruby configuration namespaces](#ruby-namespaces) later in this topic.

**Note**  
For platform versions prior to *Ruby 2.7 AL2 version 3.3.7*, the default Elastic Beanstalk nginx proxy server configuration doesn't support serving static files from the domain root (`subdomain.elasticbeanstalk.com/`). This platform version was released on October 21, 2021. For more information see [New platform versions - Ruby](https://docs.aws.amazon.com/elasticbeanstalk/latest/relnotes/release-2021-10-21-linux.html#release-2021-10-21-linux.platforms.ruby) in the *AWS Elastic Beanstalk Release Notes*.

### Environment properties


The **Environment Properties** section lets you specify environment configuration settings on the Amazon EC2 instances that are running your application. Environment properties are passed in as key-value pairs to the application.

The Ruby platform defines the following properties for environment configuration:
+  **BUNDLE\$1WITHOUT** – A colon-separated list of groups to ignore when [installing dependencies](http://bundler.io/bundle_install.html) from a [Gemfile](http://bundler.io/v1.15/man/gemfile.5.html).
+ **BUNDLER\$1DEPLOYMENT\$1MODE** – Set to `true` (the default) to install dependencies in [deployment mode](https://bundler.io/man/bundle-install.1.html#DEPLOYMENT-MODE) using Bundler. Set to `false` to run `bundle install` in development mode.
**Note**  
This environment property isn't defined on Amazon Linux AMI Ruby platform branches (preceding Amazon Linux 2).
+  **RAILS\$1SKIP\$1ASSET\$1COMPILATION** – Set to `true` to skip running [http://guides.rubyonrails.org/asset_pipeline.html#precompiling-assets](http://guides.rubyonrails.org/asset_pipeline.html#precompiling-assets) during deployment.
+  **RAILS\$1SKIP\$1MIGRATIONS** – Set to `true` to skip running [http://guides.rubyonrails.org/active_record_migrations.html#running-migrations](http://guides.rubyonrails.org/active_record_migrations.html#running-migrations) during deployment.
+  **RACK\$1ENV** – Specify the environment stage for Rack. For example, `development`, `production`, or `test`.

Inside the Ruby environment running in Elastic Beanstalk, environment variables are accessible using the `ENV` object. For example, you could read a property named `API_ENDPOINT` to a variable with the following code:

```
endpoint = ENV['API_ENDPOINT']
```

See [Environment variables and other software settings](environments-cfg-softwaresettings.md) for more information.

## Ruby configuration namespaces


You can use a [configuration file](ebextensions.md) to set configuration options and perform other instance configuration tasks during deployments. Configuration options can be [platform specific](command-options-specific.md) or apply to [all platforms](command-options-general.md) in the Elastic Beanstalk service as a whole. Configuration options are organized into *namespaces*.

You can use the `aws:elasticbeanstalk:environment:proxy:staticfiles` namespace to configure the environment proxy to serve static files. You define mappings of virtual paths to application directories.

The Ruby platform doesn't define any platform-specific namespaces. Instead, it defines environment properties for common Rails and Rack options.

The following configuration file specifies a static files option that maps a directory named `staticimages` to the path `/images`, sets each of the platform defined environment properties, and sets an additional environment property named `LOGGING`.

**Example .ebextensions/ruby-settings.config**  

```
option_settings:
  aws:elasticbeanstalk:environment:proxy:staticfiles:
    /images: staticimages
  aws:elasticbeanstalk:application:environment:
    BUNDLE_WITHOUT: test
    BUNDLER_DEPLOYMENT_MODE: true
    RACK_ENV: development
    RAILS_SKIP_ASSET_COMPILATION: true
    RAILS_SKIP_MIGRATIONS: true
    LOGGING: debug
```

**Note**  
The `BUNDLER_DEPLOYMENT_MODE` environment property and the `aws:elasticbeanstalk:environment:proxy:staticfiles` namespace aren't defined on Amazon Linux AMI Ruby platform branches (preceding Amazon Linux 2).

Elastic Beanstalk provides many configuration options for customizing your environment. In addition to configuration files, you can also set configuration options using the console, saved configurations, the EB CLI, or the AWS CLI. See [Configuration options](command-options.md) for more information.

# Installing packages with a Gemfile on Elastic Beanstalk
Gemfile

To use RubyGems to install packages that your application requires, include a `Gemfile` file in the root of your project source.

**Example Gemfile**  

```
source "https://rubygems.org"
gem 'sinatra'
gem 'json'
gem 'rack-parser'
```

When a `Gemfile` file is present, Elastic Beanstalk runs `bundle install` to install dependencies. For more information, see the [Gemfiles](https://bundler.io/man/gemfile.5.html) and [Bundle](https://bundler.io/man/bundle.1.html) pages on the Bundler.io website.

**Note**  
You can use a different version of Puma besides the default that's pre-installed with the Ruby platform. To do so, include an entry in a `Gemfile` that specifies the version. You can also specify a different application server, such as Passenger, by using a customized `Gemfile`.  
For both of these cases you're required to configure a `Procfile` to start the application server.  
For more information see *[Configuring the application process with a Procfile](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/ruby-platform-procfile.html)**.* 

# Configuring the application process with a Procfile on Elastic Beanstalk.
Procfile

To specify the command that starts your Ruby application, include a file called `Procfile` at the root of your source bundle.

**Note**  
Elastic Beanstalk doesn't support this feature on Amazon Linux AMI Ruby platform branches (preceding Amazon Linux 2). Platform branches with names containing *with Puma* or *with Passenger*, regardless of their Ruby versions, precede Amazon Linux 2 and don't support the `Procfile` feature.

For details about writing and using a `Procfile`, see [Buildfile and Procfile](platforms-linux-extend.build-proc.md).

When you don't provide a `Procfile`, Elastic Beanstalk generates a default `Procfile`. If your `Gemfile` includes Puma, Elastic Beanstalk assumes you want to use your provided version of Puma and generates the following default `Procfile`.

```
web: bundle exec puma -C /opt/elasticbeanstalk/config/private/pumaconf.rb
```

If your `Gemfile` does not include Puma, Elastic Beanstalk assumes you're using the pre-installed Puma application server and generates the following default `Procfile`. On Amazon Linux 2 Ruby platform branches, Elastic Beanstalk always generates the following default `Procfile` if you don't provide a `Procfile`.

```
web: puma -C /opt/elasticbeanstalk/config/private/pumaconf.rb
```

**Note**  
On [October 10, 2024](https://docs.aws.amazon.com/elasticbeanstalk/latest/relnotes/release-2024-10-10-al2-10-2024-retire.html), the last Ruby Amazon Linux 2 platform branches were retired. All currently [supported Ruby platform branches](https://docs.aws.amazon.com/elasticbeanstalk/latest/platforms/platforms-supported.html#platforms-supported.ruby) are based on Amazon Linux 2023. For information about migration, see [Migration from Amazon Linux 2 to Amazon Linux 2023](using-features.migration-al.generic.from-al2.md).

If you want to use the Passenger application server, use the following example files to configure your Ruby environment to install and use Passenger.

1. Use this example file to install Passenger.  
**Example Gemfile**  

   ```
   source 'https://rubygems.org'
   gem 'passenger'
   ```

1. Use this example file to instruct Elastic Beanstalk to start Passenger.  
**Example Procfile**  

   ```
   web: bundle exec passenger start /var/app/current --socket /var/run/puma/my_app.sock
   ```

**Note**  
You don't have to change anything in the configuration of the nginx proxy server to use Passenger. To use other application servers, you might need to customize the nginx configuration to properly forward requests to your application.