Initialize Your Application

$ rails new my-app

#
# It creates files and run 'bundle install'
#

$ git init
$ git add .
$ git commit --message="Base rails application"

Create Your Application on Scalingo

$ scalingo create my-app
Git repository detected: remote scalingo added
→ 'git push scalingo master' to deploy your app

Provision and Configure Your Database

• Go on the dashboard of your application.
• Select the Addons category
• Choose the database you want to use

PostgreSQL®

Add the gem pg to your Gemfile.

With the PostGIS Extension

In order to deal with geographic data, you may want to enable PostGIS. It is often used with the gem activerecord-postgis-adapter. In case you face the following error message:

Unknown key: :geographic.

Fixing this error requires to update the Rails configuration file config/database.yml with:

url: <%= ENV["DATABASE_URL"]&.gsub(/postgres:/, 'postgis:') %>

MySQL®

Add the gem mysql to your Gemfile:

gem 'mysql2', '~> v0.3.18'

Then set the following environment variable:

• DATABASE_URL → Copy the value of SCALINGO_MYSQL_URL and replace ‘mysql://’ by ‘mysql2://’

MongoDB®

To use a MongoDB® database your need to add the gem mongoid to your Gemfile. Please refer to this guide.

Setup Your Application Logging

By default, Rails applications don’t write their logs to STDOUT but in a custom file. We expect your application to write all its logging entries to STDOUT and STDERR according to their nature, in accordance to the 12-factor.

Why writing the logs to the standard output?

It is a requirement to let the platform aggregate them and let you browse your application logs in the dashboard or with Scalingo’s command line interface.

Rails 5 and Later

You’ve nothing to do, everything is handled by the platform

Rails 4 and Before

• Add the following gem in your Gemfile: gem "rails_12factor"

The rails_12factor gem includes two gems, one of them is rails_stdout_logging. Thanks to it, the application won’t write the logs to the log/production.log file but directly on the standard output.

Serving Static Assets

All assets in the /public folder are automatically accessible. E.g. a file named robots.txt would be reachable at the address https://my-app.osc-fr1.scalingo.io/robots.txt.

Finalize and Deploy

$ bundle install
$ git add .
$ git commit -m "Configure application for Scalingo"
$ git push scalingo master

Database Migration

To run a migration, you need to use a post-deployment hook.

The Ruby on Rails application starts up before the schema has changed, but does not receive a query. The way ActiveRecord works on Rails is that the schema is loaded into memory on the first query on a given table.

As a result, if operations are started before the migration has been executed (per example initializers or an asynchronous worker), the application may load the schema pre-migration. A restart could be necessary after the migration.

The best practice is to perform non-destructive migrations, where a column rename is performed in several steps, rather than an ALTER TABLE renaming a column.

A good example in strong_migrations gem documentation.

Access Your Application

…
Waiting for your application to boot...
<-- https://my-app.osc-fr1.scalingo.io -->

A new application will render a 404 error The page you were looking for doesn't exist., but it’s expected. There is nothing in the project, it’s time to build your product!

Specifying a Custom Node.js Runtime

Latest version of Rails application also use Node.js in case ExecJS or Webpacker is detected. The Node.js version built inside the Ruby buildpack is frozen. It is the latest version of the LTS 22.x at the time of writing.

If you ever need to specify a different version of Node.js, you need to setup the multi buildpacks), in order to use both the Node.js and the Ruby buildpack. The content of your .buildpacks file must respect the following order between the buildpacks:

https://github.com/Scalingo/nodejs-buildpack.git
https://github.com/Scalingo/ruby-buildpack.git

You also need to remove the file bin/yarn if it already exists.

You eventually need to specify the Node.js version in your package.json.

Configure Webpacker

Important: Webpacker is no longer maintained from Rails 7+. It should not be used in Rails 8. The official recommendation is to migrate to jsbundling-rails. This offers more flexibility with different bundlers like esbuild, rollup.js, bun, or webpack.

For Rails 7+ Applications

Create new Rails 7+ applications using jsbundling-rails instead of Webpacker. Refer to the jsbundling-rails repository and the advanced asset management guide for more details.

For existing applications using Webpacker

You may see the following error when deploying a Rails application which uses Webpacker:

error Command "webpack" not found.

In order to fix this error, execute the locally the following commands:

bundle exec rails yarn:install
bundle exec rails webpacker:install

Commit and push the binstubs:

git add bin/*
git commit -m "Add Yarn and Webpacker binstubs"
git push scalingo master

Recommended migration path

Migrate applications currently using Webpacker to jsbundling-rails with Webpack or another bundler. Follow the official migration guide for this approach.

Enable Webpack Compilation Output for Debugging

To see detailed webpack logs during deployment and debug webpack compilation issues, you need to enable webpack compilation output in your config/webpacker.yml file:

# config/webpacker.yml
production:
  # ... other configuration options
  webpack_compile_output: true

This setting is espacilly useful when webpack fails during deployment, as it will show you detailed error messages and warnings that can help identify the root cause of compilation issues.

Important: Without webpack_compile_output: true, webpack errors may appear as generic failures without detailed information, making debugging much more difficult.

Common Webpack Deployment Issues

If you encounter webpack compilation errors during deployment, here are some common troubleshooting steps:

1. Check your webpack logs: Ensure webpack_compile_output: true is set in your production environment
2. Verify asset compilation locally: Run RAILS_ENV=production bundle exec rails assets:precompile locally to test
3. Check for missing dependencies: Ensure all required packages are listed in your package.json
4. Memory issues: Large webpack builds may require additional memory during compilation

Example of typical webpack error output when debugging is enabled:

WARNING: 4 repetitive deprecation warnings omitted.

Precompiling assets failed.
An error occurred during buildpack compilation
Error deploying the application
Invalid return code from buildpack

With proper logging enabled, you’ll see more detailed information about what specifically failed during webpack compilation process.

Use VIPS to Process Image

Since Rails 7 the default image processing tool for ActiveStorage has been replaced from ImageMagick to VIPS. As VIPS isn’t installed by default in our stack, you will need to install the libvips-dev package using the APT Buildpack.

Some functionalities, for example HEIF support, will be available only by adding optional package dependencies, see VIPS documentation for more information.

Specify a Secret Key Base

Starting with Rails 4.1, you can now specify a secret key base, which is used as the input secret to the application’s key generator.

By default, this value is randomly generated by Scalingo. You can change this default value by setting the SECRET_KEY_BASE environment variable in your application.