Deploying Ruby on Rails apps

Clever Cloud allows you to deploy any Ruby on Rails application. This page will explain you how to set up your application to run it on our service.

You do not need to change a lot in your application, the requirements will help you configure your applications with some mandatory files to add, and properties to setup.


Ruby on Rails is an open source web application framework which runs on the Ruby programming language. It is a full-stack framework: it allows creating pages and applications that gather information from the web server, talk to or query the database, and render templates out of the box. As a result, Rails features a routing system that is independent of the web server.

Here is an example of Ruby on Rails on Clever Cloud.

Create an application

Refer to the page Deploy an application on Clever Cloud.

Necessary information

Be sure that:

  • you push to the master branch

  • you commit your gems.locked or Gemfile.lock file

  • you have a file (This one is most of the time generated by rails)


First, your application must use rack. This implies that a file is present.

Then, you need to provide a gems.locked or Gemfile.lock. To do that, please run:

.../myapp $ bundle install ## This will generate gems.locked or Gemfile.lock
.../myapp $ git add gems.locked ## or Gemfile.lock
.../myapp $ git commit -m "Add production dependency file"

Environment injection

To access your variables in your application, nothing simpler! Just get it from your environment, like you would with PATH: ENV["MY_VARIABLE"].

Choose ruby version

If you specify a ruby version in your gems.rb of Gemfile, we'll use it, otherwise; keep reading.

On your Clever Cloud application create an environment variable RUBY_VERSION=rubyversion where rubyversion represents:

  • "2" will select the greatest "2.X.Y" version available.
  • "2.5" will select the greatest "2.5.Y" version available.
  • "2.5.3" will select the "2.5.3" version.

If given rubyversion does not match any available version, your deployment will fail.

If you need a version that is not yet installed, please contact the support to ask for the version to be added. We try to follow the releases, but, hey, we're human!

Due to current landscape in ruby applications, the default version is the greatest 2.5.Y. We provide also the 2.4.Y and 2.3.Y version.

Choose rackup application server

You can select the server by setting an environment variable CC_RACKUP_SERVER=yourserver. The only available server as of now is puma. puma is the default application server from rails, and thus one of the most commonly used for ruby deployment.

By default, when creating a new ruby application, an environment variable is automatically added: CC_RACKUP_SERVER=puma.

If you select puma, you will need to also add it to your dependencies: bundle add puma, and commit the resulting changes (this is automatic for projects generated using rails new).

Configuration secret key production

You need to use environment injection for secret_key_base in file ./config/secret.yml :

  # You can use `rake secret` to generate a secure secret key.
  # Do not keep production secrets in the repository,
  # instead read values from the environment.
    secret_key_base: <%= ENV["SECRET_KEY_BASE"] %>

Clever Cloud can inject environment variables that are defined in the dashboard and by add-ons linked to your application.

More configuration

You can configure your deployment via the clevercloud/ruby.json configuration file. This file is optional.

Set deployment RUBY_ENV and rake goals to execute

  "deploy" : {
    "env": "<string>",
    "rakegoals": [<string>],
    "sidekiq": true

The following table describes each field:

Usage Field Description
Optional deploy.env This field is only used for overriding the default "production" RAILS_ENV value.
Optional deploy.rakegoals Specify a list of rake goals to execute. They will be executed in the order of the list:
bundle exec rake "goal1"

bundle exec rake "goal2"

We do not execute any rake goals by default.
Optional deploy.sidekiq Run a sidekiq process in background. Please note you will need a redis instance to use this feature.

The sidekiq field can also be an array of strings instead of a boolean, like this:

"sidekiq":  [

Each string is the path from the root of the repository to a sidekiq configuration file. Each file might contain something like the following:

:concurrency: 4
:pidfile:     tmp/pids/
  - [critical, 2]
  - default

  :logfile: ./log/sidekiq.log

It's a standard sidekiq.yml configuration file.

Assets and static files

Static files are configured with environment variables:

STATIC_FILES_PATH: should point to a directory where your static files are stored.

STATIC_URL_PREFIX: the URL path under which you want to serve static files (e.g. /public/)

Also, you are able to use a Filesystem Bucket to store your static files. Please refer to the File System Buckets section.

Note: the path of your folder must be absolute regarding the root of your application.

Note: setting the STATIC_URL_PREFIX to / will make the deployment to fail.

Note: if your project uses webpacker, make sure to enable the dedicated build instance option in the information tab of your application because webpacker needs a lot a ressources when starting.

If you use the asset pipeline, make sure to include the assets:precompile task in the rakegoals field of clevercloud/ruby.json.

    "deploy": {
        "rakegoals": ["db:migrate", "assets:precompile"]

Using Active Storage and Cellar S3

Only for Rails >= 5.2.

  • Enable Active Storage for your application: $ rails active_storage:install then $ rake db:migrate
  • Add gem "aws-sdk-s3", require: false to your Gemfile, run $ bundle install
  • Add config.active_storage.service = :clevercloud in config/environments/production.yml
  • Add in config/storage.yml:
  service: S3
  access_key_id: <%= ENV['CELLAR_ADDON_KEY_ID'] %>
  secret_access_key: <%= ENV['CELLAR_ADDON_KEY_SECRET'] %>
  region: us-east-1
  bucket: <%= ENV['CELLAR_ADDON_BUCKET_NAME'] %>
  endpoint: <%= ENV['CELLAR_ADDON_ENDPOINT'] %>
  force_path_style: true
  • In the clever cloud console create a Cellar S3 storage add-on, name it, link it to your rails application and create a bucket.
  • In the environment variables section of your Ruby on Rails application on Clever Cloud add the following environment variables:
CELLAR_ADDON_BUCKET_NAME=<your bucket name>

You can now commit and push your changes.

nginx configuration

nginx settings can be configured by setting environment variables:

  • NGINX_READ_TIMEOUT: the response timeout in seconds. (Defaut: 300)

Nginx settings can be configured further in clevercloud/http.json. All its fields are optional.

  • languages: configure a default language and redirections
  • error_pages: configure custom files for error pages
  • force_https: automatically redirect HTTP traffic to HTTPS
  • aliases: set up redirections
  • charset: force a specific charset
    "languages": {
        "default": {"rewrite": "en"},
        "fr": {"rewrite": "en"}
    "error_pages": {
        "404": "path/to/page"
    "force_https": true,
    "aliases": {
        "/path": "redirection"
    "charset": "latin-1"

Puma configuration

Puma reads its configuration from the config/puma.rb file. See the puma documentation for more information.

You can override the number of workers by using the CC_PUMA_WORKERS environment variable (e.g. CC_PUMA_WORKERS=2). If specified, it will be preferred over the setting from config/puma.rb. If none is specified, we will setup the number of workers depending on the size of the scaler your application is running on. We also fill the WEB_CONCURRENCY environment variable if it's not present as it may be used by rails' puma configuration.

You can override the number of threads per worker by using the CC_PUMA_THREADS environment variable (e.g. CC_PUMA_THREADS=4). You can either specify a raw number or a range (e.g. CC_PUMA_THREADS=4:8) to configure a minimum and maximum number of threads instead of a static number of threads. If specified, it will be preferred over the setting from config/puma.rb. If none is specified, we will setup the number of threads per worker depending on the size of the scaler your application is running on. We also fill the RAILS_MAX_THREADS environment variable if it's not present as it may be used by rails' puma configuration.

Deploy on Clever Cloud

Application deployment on Clever Cloud is via Git. Follow these steps to deploy your application.

Edit me on GitHub