DEV Community: Brena Monteiro

Diving into Custom Exceptions in Ruby

Brena Monteiro — Wed, 05 Apr 2023 14:15:42 +0000

Customizing exceptions is usually not a common concern during software development. But if you catch an error in an observability tool and can't correctly and quickly identify the problem, you may need more information and details about an exception.

This article will show you how to customize exceptions in Ruby and mitigate potential future problems due to a lack of error information.

Let's dive straight in!

A Quick Side-Note

This post is a natural progression to Debugging in Ruby with AppSignal, so we recommend reading that first for an overview of debugging and an introduction to custom exceptions.

How to Rescue an Exception with Ruby

Ruby has a class called Exception, from which error-handling classes inherit. In this section, we'll better understand Ruby's structural exception flow before we create our custom exception.

Exception is the main exception class in Ruby, and rescue Exception will catch all exceptions inherited from Exception. It isn't best practice to use this in our app, as it will catch all exceptions used internally by Ruby.

The easiest way to rescue an exception in Ruby is to create a begin ... rescue block of code like the example below:

begin
  call_some_method()
rescue Exception => e
  ...
end

Since Exception will catch all exceptions, we should try to use something more specific to filter and get only the error we want. One example is the StandardError class, a standard rescuer used to catch exceptions related to application code errors by ignoring Ruby's internal exceptions.

To catch a StandardException, you can use the example below:

begin
  call_some_method()
rescue StandardException => e
  ...
end

Or, if no exception class is stated, Ruby will return the exceptions handled by the StandardException class.

begin
  call_some_method()
rescue => e
  ...
end

To create a custom exception with Ruby, you'll probably create a class that inherits from StandardError. We'll cover that in the next few sections.

To learn more about exceptions and find the best one to inherit, check Ruby's exceptions list.

Adding Additional Information to the Ruby Exception

Creating a new exception without sending relevant information will not effectively help in debugging — identifying and fixing — the problem. You need to add the error details. Here, we will see how to pass information from objects to the custom exception.

Let's create a new custom exception just to receive the data we want to log. As mentioned in the previous section, the custom exception needs to inherit from StandardError.

You can use a simple Rails project to test this implementation. Create a new folder called exceptions inside the app folder and a class called custom_exception.rb in your Rails project.

# app/exceptions/custom_exception.rb

class CustomException < StandardError
  def initialize(code, name, msg, details)
    @code = code
    @name = name
    @msg = msg
    @details = details
  end
end

In this exception class, we can define all the information that needs to be shown in the logs and we use four attributes for our data:

a code to enumerate the exception
a name
an informational message
internal information details about the exception already provided by Ruby

And now we create a begin...rescue block to raise the CustomException and pass the parameters to the exception attributes.

# app/models/employee.rb

class Employee
  def calculate_fees
    begin
      nil.object # Any code that throws an exception.
    rescue => exception
      raise CustomException.new(
        333,
        "My customized exception",
        "A new exception occurred in the application",
        exception)
    end
  end
end

This looks useful, so let's continue the implementation and use this data to customize the exception log.

Extending an Exception in Ruby

Extending an exception allows us to elevate customization to a more specific and reusable level. Just as Ruby has several exceptions for different types of errors, we can also follow this line of programming in our systems.

Next, let's understand how to override our exception and use it in a context that demands an extension.

Finding information in logs is a painful activity. Developers often blame themselves for not including more information about errors or how to search and filter. If you are not using any monitoring tools that provide this, including meaningful data could save you in the foreseeable future.

Pro-tip: Check out the section on 'Debugging Exceptions in Ruby with AppSignal' in our post Debugging in Ruby with AppSignal for information about how to set up and track custom exceptions in AppSignal.

In the example below, we will customize the display of exceptions in the log. Initially, you might think that it's just a light and pretty way to show data. However, the keywords used in the data are key to finding an error and helping whoever will be monitoring the application.

Add the colorize gem to your project by including the code below in your Gemfile.

# Gemfile

gem 'colorize'

Run the bundle to install the colorize gem and launch your Rails application.

$ bundle install
$ rails s

Now, in your exception class, import the gem. Print the attributes in a formatted way, so it's easy to see and quickly find an important error.

# app/exceptions/custom_exception.rb

require 'colorize'

class CustomException < StandardError
  def initialize(code, name, msg, details)
    ...
    log_exception
  end

  def log_exception
    print_separator

    STDERR.puts "🚨🚨🚨 #{self.class} 🚨🚨🚨".colorize(:red)

    self.instance_variables.each do |attr|
      # All attributes will be printed.
      STDERR.puts "#{attr}: #{self.instance_variable_get(attr)}".colorize(:red)
    end

    print_separator
  end

  def print_separator
    85.times { print "-".colorize(color: :black, background: :red) }
    STDERR.puts "\n"
  end

  def to_s
    @name.colorize(:red)
  end
end

Check out the result of this visual customization and test some options to create your format and style.

Wrapping Up and Next Steps

In this post, we covered how to customize and highlight a Ruby exception in your logs. Many other customizations are possible, but what's most important is that you handle the exceptions relevant to your application. And remember, don't apply the same formatting style to all exceptions, as Rails already does.

Happy coding!

P.S. If you'd like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!

Improve Code in Your Ruby Application with RubyCritic

Brena Monteiro — Wed, 26 Oct 2022 12:02:12 +0000

RubyCritic provides visual reports highlighting code smells, code structure, ease of testing, and test coverage in your Ruby application.

It's in active development, with new code analysis tools often being introduced as new features. It's well worth keeping track of RubyCritic's releases.

This article will touch on some of RubyCritic's benefits, its dependencies, and how to read its code reports.

Let's get going!

Why Choose RubyCritic for Your Ruby on Rails Application?

You should consider using RubyCritic if you want a single place to review code improvements for your project. Including RubyCritic in your development process will certainly reduce the time a development team spends working on technical debts. Most technical debts will be mapped out at development time.

Some benefits that RubyCritic can provide to your project and development process include:

Unified information in one place
Visual reports
Easy installation
Zero configuration
Customization allowed
Being extensible — you can make your own open-source integration
A badge generator 🎉

To understand how RubyCritic works, let's look at the internal dependencies it uses to make reports.

Internal Dependencies in RubyCritic

When you add RubyCritic to your project, some dependencies will also be included.

Let's highlight the dependencies that make magic happen: the Reek, Flay, and Flog gems. These dependencies allow RubyCritic to show you valuable information about your code. Understanding how they work also makes RubyCritic easier to use.

Reek: Detect Code Smells in Ruby

Reek is a gem for detecting code smells in Ruby. A bad smell in code is not about identifying wrong code, it is more about analyzing if the code could be written better.

Reek's analysis identifies if something could be implemented in another way. It does not suggest how, as most code smells are associated with business logic and a developer's experience with a language.

For example, you could easily rewrite an if statement using metaprogramming techniques. The way to correct it, though, is up to a developer according to a project's context. In this case, no library will be able to indicate the best solution.

Reek detects an extensive list of smells. It examines and identifies possible smells in:

Classes
Attributes
Methods
Parameters
Modules
Iterators
The implementation of polymorphism

By finding smells, you can take steps to make your code more readable and maintainable.

Reek allows for custom configuration to:

Disable a detector by its type
Exclude directories from being scanned
Use filters to silence warnings

You can even define specific code to suppress in a scan, a very useful feature when code is not yet finalized or refactored, or even if it is legacy code.

Let's see a sample of how Reek works. In this code, the exception is just defined as e.

# app/controllers/erp/orders_controller.rb

def create
  ...

  rescue JSON::Schema::ValidationError => e
    render status: :unprocessable_entity, json: {
      type: "invalid-schema",
      title: "Your request does not match the expected schema.",
      detail: e.message
    }
  end
end

It is easy to imagine that e means an exception, but what if we have other exceptions? Identifying them correctly is the best way to maintain good code.

Reek will identify e as UncommunicativeVariableName and show a warning.

$ reek app/controllers/erp/orders_controller.rb
Inspecting 1 file(s):
S

app/controllers/erp/orders_controller.rb -- 1 warning:

  [91]:UncommunicativeVariableName: Erp::OrdersController#create has the variable name 'e' [https://github.com/troessner/reek/blob/v6.1.1/docs/Uncommunicative-Variable-Name.md]

Flay: Check for Ruby Code Duplication

Flay identifies structural Ruby code similarities, including:

Detecting code duplication within a project
Checking the difference at any code level
Generating a score to measure how good your code is (the lower your score, the better the code)

If Flay reports a similarity in your code, it's a high indicator that refactoring is needed. Don't ignore this! Duplicate code is a gateway to bugs. If you fix something in one place but forget about another, more bugs appear.

We can check how Flay works by running it in its own source code:

$ flay lib/flay.rb
Total score (lower is better) = 36

1) Similar code found in :iter (mass = 36)
  lib/flay.rb:80
  lib/flay.rb:105

Flay identifies similarities between these two:

# lib/flay.rb:80
opts.on("-m", "--mass MASS", Integer, "Sets mass threshold (default = #{options[:mass]})") do |m|
  options[:mass] = m.to_i
end

# lib/flay.rb:105
opts.on("-t", "--timeout TIME", Integer, "Set the timeout. (default = #{options[:timeout]})") do |t|
  options[:timeout] = t.to_i
end

Note that the code's spelling is not exactly the same, but its functionality is and can be refactored to avoid duplication. That's the magic of Flay!

Flog: Examine Your Code Complexity in Ruby

Flog checks how difficult your code is to test. It sets a complexity score for each line of code and sums up the score for each method and class.

The higher the score, the more your code needs to be refactored because it signifies that you have a highly complex implementation.

Let's see Flog in action! A small change can cause your score to variate.

def validate_expiration
  return if exp_month.blank? || exp_year.blank?

  ...
end

$ flog app/models/credit_card.rb

5.2: CreditCard#validate_expiration   app/models/credit_card.rb:12-15

Note that in the first part of the code, we have an or check that increases the score by 0.4 points.

def validate_expiration
  return if exp_month.blank?
  return if exp_year.blank?

  ...
end

$ flog app/models/credit_card.rb

4.8: CreditCard#validate_expiration app/models/credit_card.rb:12-15

Other RubyCritic Dependencies

RubyCritic also uses other runtime dependencies, such as:

byebug - this elevates debugging Ruby applications. It allows you to run a program line by line, add breakpoints, and evaluate and track values at runtime. If you still use puts for debugging, it's time you get to know Byebug's features and commands.
rubocop - a linter for Ruby code that helps you follow a style guide used by the Ruby community, or even apply your own code style. It's very useful to set standards in your team and avoid silly conflicts about spaces and tabs.
SimpleCov - a tool to check Ruby application code coverage. You can configure it to run alongside your tests. It provides metrics on code coverage so that you can identify what you need to pay attention to and where to invest your time to create better test cases.

Dive into RubyCritic's list of dependencies.

Using RubyCritic for Your Ruby on Rails App

RubyCritic has good documentation to help you get started without much configuration. Therefore, we will focus on utilizing its resources to help us analyze its reports.

RubyCritic provides 'Code', 'Smells', and 'Coverage' reports. We'll look at each of these features in turn.

The Overview in RubyCritic

The 'Overview' page shows a total score for your project on a donut chart, along with ratings (A being the best rating, F the worst). The 'Summary' section shows the details of each rating, including the number of files, churns (commit changes), and smells found.

In the 'Churn vs Complexity' section here, it is already possible to identify the class with the greatest complexity, which should probably be the first point of attention.

To better understand this graph, it is worth recapping code churn. Code that changes frequently can raise an alert that something is wrong — maybe in the logic or the business domain, for example. Either way, looking at 'Churn vs Complexity' can help you see where the pain points are across your project.

Code Report

The 'Code' report shows a score for each class, including indicators for churn, complexity, duplication, and smells.

You can sort this list by any column to view the highest ranking factors and address the most critical issues first.

In addition, this list has a filter that allows you to search by class name quickly.

Clicking on the class name will open a detailed page with the class code and metrics such as:

Code line
Quantity methods
Calculated churn
Complexity by method
Complexity score (total per class)
Amount of duplicates found
Number of smells

The line of code where an issue is found will be highlighted (based on information provided by the Reek gem).

If Flog identifies any issues, you'll see a score. You'll also see if a Flay report has detected any duplicate code.

Smells Report

The 'Smells' page displays the smell type, the exact location where a smell appears, and the fix status.

As mentioned earlier, the smells are detected by Reek, and sorting and filtering are also available on this page.

Clicking on a class name will open a page with your code details. You can also see the classes grouped by smell type (this is missing from the 'Code' page, which only displays the number of smells).

Coverage Report

Finally, you can see class classifications and the percentage of coverage for each class in the 'Coverage' report. In contrast to the lists on the 'Code' and 'Smells' reports, the list in 'Coverage' does not allow information to be sorted and filtered.

You can only see the percentage of code coverage — no additional information is available.

Integrating the SimpleCov report could add more value and usefulness to this page. But in any case, the 'Coverage' report can help if you need a simple report to examine your project's test coverage.

Wrap Up

In this post, we briefly looked at the benefits of RubyCritic for your Ruby application before diving into its internal dependencies: Reek, Flay, and Flog. We then ran through how to read and analyze RubyCritic's reports.

As a next step, figure out how to use RubyCritic in your pipeline.

Happy code refactoring!

P.S. If you'd like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!

Debugging in Ruby with AppSignal

Brena Monteiro — Wed, 28 Sep 2022 14:38:08 +0000

An application monitoring tool (APM) is not just useful for seeing how your application performs through graphs and visuals. We can go deeper and use an APM to understand how your application behaves in a certain environment.

As developers, we should aim to be less reactive to errors and more predictive, avoiding crashes for end-users.

One way to accomplish this is by using monitoring tools to debug our application when an error occurs. AppSignal has advanced features that allow us to intelligently debug our logs and thus reflect this precautionary thinking in our applications.

This article will show you how to better log and debug your Ruby application using AppSignal.

Integrate Your Ruby App with AppSignal

To start debugging with AppSignal, you need to have an AppSignal account.

Integrate your Ruby application with AppSignal by following the steps in the article 'Ruby on Rails Application Monitoring with AppSignal'.

Log Options

Now that you have an application set up to send logs to AppSignal, let's look at the logging options for your Ruby application.

AppSignal offers various log levels for your application according to your project's needs. In this section, we will explore the difference between each log level.

At first glance, we might think these logs are related to the application logs shown in the 'Backtrace' section of AppSignal.

However, changes to log_level won't reflect the information displayed in the backtrace. It is important to understand that setting the log_level value relates to AppSignal's communication logs with your application. It has nothing to do with application logs.

This means that when we set the logging level in our application, we change the type of information that appears in the application logs about execution and integration with AppSignal.

In most cases, you can just set the log_level to error (unless you've had an issue with the AppSignal integration and need to send log information to AppSignal's Support team). The log_level must be defined in config/appsignal.yml, as in the example below:

# config/appsignal.yml

production:
  <<: *defaults
  log_level: error

Watch the application logs when we set error, warning, or info to log_level. We will see pretty much the same information in the logs.

Now, check out the logs when we set log_level as debug.

Finally, let's see what happens when we set log_level as trace.

Ignore Your Ruby App's Predicted Errors in AppSignal

You don't need to catch and keep all errors in logs. Some common errors can be expected in an application — we don't need to inflate our logs with 404 errors, for example. Now let's configure AppSignal to ignore errors that are irrelevant to trace.

Ignoring an error is useful when a production bug has already been identified, but the fix is still in development. We already know about the problem's existence, so there's no need to keep filling the error monitoring tool or be notified about it. We can ignore the error's appearance until the patch deployment goes into production. This approach can be applied to all known bugs that have already been cataloged in the issues list.

We can also ignore errors when we know that a service our application communicates with will be down for maintenance. This way, we don't flood the monitoring tool with errors regarding expected maintenance, alerting our monitoring team unnecessarily.

AppSignal's gem provides three ways to handle and ignore predicted errors.

`ignore_errors`

ignore_errors helps when you need to ignore all errors generated by a class error or when you don't know the exact error that could happen from there.

Maybe your application needs to do many math calculations, and AppSignal doesn't need to track all related errors. ignore_errors will reduce the errors list and only keep issues that need to be addressed.

`ignore_actions`

This is useful if you know exactly which method will generate an error you don't need to trace — for example, a method that will be re-executed until it succeeds. You can also use ignore_actions for queue processing when another monitoring tool handles logs specific to queue item failures.

`ignore_namespace`

ignore_namespace is great if you have an application separated by domain and want to group errors. Maybe you have a specific module to treat payments or to process an order in the background. Grouping it in a namespace for jobs makes sense. Then you can ignore the exceptions that occur inside this namespace.

Configure in Your Ruby App

Include ignore_errors, ignore_actions, and ignore_namespace in your config/appsignal.yml file, with a list of classes to ignore when this error occurs in your application.

# config/appsignal.yml

production:
  <<: *defaults
  ignore_errors:
    - Net::HTTPGatewayTimeout
    - NoMethodError
  ignore_actions:
    - HomeController#index
  ignore_namespace:
    - jobs
    - payment

Debugging Exceptions in Ruby with AppSignal

Now that we know how to ignore irrelevant errors, it's time to deal with the errors that matter. AppSignal provides functions to configure how an error is sent from your application to the AppSignal monitor. Let's learn about the listen_for_error feature and extract valuable information from exceptions.

Sometimes, we have a situation where an exception may or may not be thrown due to some parameters (if a job is not running or even if an external endpoint is unavailable). We still want to send detailed information to AppSignal, not just the exception itself. For this case, we'll create a custom exception and use it to send helpful information to the monitoring team.

The first thing we need to do is create a class for our custom exception. Make a new folder called exceptions inside your application directory. Then create a new class called CustomException inherited from StandardError. You can define any information as the content of this exception. By default, an exception already has msg as an attribute.

In this example, you need to include an exception name and the content field to report all details about the exception. In the exception constructor, all attributes are set and the method to send to AppSignal is called.

The block inside Appsignal.listen_for_error is where the magic happens! The raise will send the exception content to AppSignal in hash format to facilitate the separation of the different contents.

# app/exceptions/custom_exception.rb

class CustomException < StandardError
  attr_accessor :name, :content

  def initialize(name, msg, content)
    @name = name
    @msg = msg
    @content = content

    send_exception_to_appsignal
  end

  def send_exception_to_appsignal
    Appsignal.listen_for_error do
      exception_hash = { name: @name, msg: @msg, content: @content }
      raise "#{exception_hash}"
    end
  end
end

Now you can call this custom exception from anywhere, to use it in your application. For this example, we will include it in the controller inside the Home#index method. We need a block to handle the exception, to avoid sending it to AppSignal. The nil.object code will throw a NoMethodError exception, but this exception is handled, and only CustomException will be sent to AppSignal.

# app/controllers/home_controller.rb

class HomeController < ApplicationController
  def index
    begin
      nil.object
    rescue => e
      raise CustomException.new("Customized Exception", "A new exception occurred", e)
    end
  end
end

All done! After starting your application and accessing http://localhost:3000/home#index in your browser, you will see a page with a RuntimeError exception. In AppSignal, access the 'Errors > Issue list' to see the Customized Exception issue.

{:name=>"Customized Exception", :msg=>"A new exception occurred", :content=>#<NoMethodError: undefined method `object' for nil:NilClass>}

Wrap Up and Next Steps

AppSignal provides a well-documented gem to start truly monitoring your Ruby application. Why not test it? Send data from your local machine without deploying to see if the error configuration is how you want it.

Many other features in AppSignal make it easier to debug Ruby applications, like exception handling. Check AppSignal's Ruby documentation and choose the feature that makes the most sense in your project's context. Make your app easier to debug by decreasing the time your team needs to spend looking into the root cause of bugs in production.

Happy debugging!

P.S. If you'd like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!

Deploy Your Ruby on Rails App Using Capistrano

Brena Monteiro — Wed, 27 Jul 2022 11:46:24 +0000

In this article, we will configure Capistrano in a Ruby on Rails application. We will then deploy the app to a cloud instance that runs Ubuntu as an operating system, independent of your hosting provider. You can use any cloud service, or even an on-premises server, to test or replicate the steps we'll take.

Once we've deployed the app, we'll look briefly at how you can monitor your app's deployments using AppSignal.

But first, you might ask: why should I use Capistrano in the first place?

Why Choose Capistrano for Your Ruby on Rails App?

You might be wondering if it still makes sense to continue using Capistrano for deployment these days. We now have many tools and services available for deployments and continuous integration.

But to answer that, we need to revisit the origin of Capistrano and its evolution to the present day. The first tag created in the Capistrano repository was in 2006. Its objective was to allow the execution of commands remotely via SSH in parallel on several machines, all using DSL. Since then, Capistrano has evolved, by adding several features to each version.

Currently at version 3 after 16 years, Capistrano continues to be actively developed and is now known as a framework for building automated deployment scripts.

So it's no longer just a tool to run commands on remote machines. In addition to Capistrano's features, many plugins and other gems specifically run with Capistrano.

Because of this and the fact that a large community still uses Capistrano, it remains a great tool for automated deployment.

Adding Capistrano to Your Ruby on Rails App

First, you'll need to configure a Ruby on Rails application to integrate it with Capistrano. You can follow Capistrano's documentation. However, it has more information than you'll need for the scope of this post. So for simplicity's sake, this article only includes the necessary steps and configuration that you will need.

To start the configuration, add the Capistrano gem in the development section of your Gemfile:

group :development do
  # Deployment
  gem "capistrano", "~> 3.10", require: false
  gem "capistrano-rails", "~> 1.3", require: false
end

You need the capistrano-rails gem to run a migration on your database and handle the assets that we will see in the next sections.

Now run bundle install to add Capistrano to your application:

bundle install

Then you can install Capistrano:

bundle exec cap install

This command will create a file called Capfile that imports and configures the required libraries. Furthermore, a file called deploy.rb (created inside the config folder) will contain all the configurations that should be included in a deployment with Capistrano.

Note: Capistrano creates a file to override the deploy.rb configuration for both the staging and production environments, but that will not be covered in this article.

With that, you're ready to start configuring and communicating between your Ruby on Rails application and the server.

Server Configuration with Capistrano for Your Rails App

In this step, we'll add instructions to the Capistrano configuration file. The instructions will communicate to your server on where your app will be deployed. This is where we'll define access information and the security configuration.

To ensure that your production environment runs the same version of Ruby as the version you use in development, use a Ruby version manager, such as RVM or rbenv (Capistrano supports both).

In this article, we'll use RVM. Make sure you have RVM installed on your development machine and production server. Also, check if your version of Ruby is the same in your environments and project.

Adding `capistrano-rvm` Gem

The Capistrano project provides a gem called capistrano-gem that lets you easily configure RVM. To include it in your project, add it to your Gemfile within your development group, and run bundle install again.

gem "capistrano-rvm"

Update your Capfile with the capistrano-rvm import:

# Capfile
require 'capistrano/rvm'

In the deploy file, add a configuration to set the Ruby version and the path to RVM (especially if you used a different path to install RVM).

If no version of Ruby is defined, Capistrano chooses the latest version that you have installed on the server where your application will be deployed.

# config/deploy.rb
set :rvm_ruby_version, "ruby-2.6.3"
set :default_env, { rvm_bin_path: "~/.rvm/bin" }

Capistrano::RVM has other settings for RVM, but the ones shown here are what you'll need to get started.

Set Up Your Server Configuration

It is good practice to define a user for the deployment. Don't forget to follow these steps on your server before you start a deployment:

Add the public key generated on your local machine to the ~/home/YOUR_USER/.ssh/authorized_keys file.
Create a key and include the public key in the code repository. This gives you access to clone your project within the production server. If you are using GitHub, you can follow this documentation.
Set permissions to write to the /var/www/ directory.

You can configure Capistrano for any environment you need. You just need to create a new configuration file inside config/deploy/<environment_name>.rb, then configure the IP or DNS, and username, to connect to your server.

# config/deploy/production.rb

server "11.22.333.444", user: "ubuntu", roles: %w{app db web}

To complete the deployment setup, include information about your application, such as the application name and code repository URL. Any information which is the same for all environments must be added to config/deploy.rb. Keep specific environment configurations in config/deploy/<environment_name>.rb.

# config/deploy.rb

set :application, "ruby_rails_app"
set :repo_url, "git@github.com:username/ruby_rails_app.git"

Set Up `capistrano-secrets-yml` Gem for Your Rails App

You should also set up the capistrano-secrets-yml gem.

Add the gem to your Gemfile and run the bundle to install:

# Gemfile
gem "capistrano-secrets-yml"

Import it into Capfile:

# Capfile
require "capistrano/secrets_yml"

Then create config/secret.yml in your application and include the secret key base as an environment variable. This variable will be created on your production server. Remember not to commit this file to your repository.

# config/secrets.yml
production:
  secret_key_base: <%= ENV["SECRET_KEY_BASE"] %>

Inside your application folder in the terminal, run this command to generate the secret key base:

$ rails secret

Copy the generated key and use it to set your SECRET_KEY_BASE on the production server. Access your production server and export the SECRET_KEY_BASE variable in the final ~/.bashrc file, so it is always available:

# ~/.bashrc
export SECRET_KEY_BASE="YOUR_SECRET_KEY_BASE"

Run the source to make it instantly available in your environment:

$ source ~/.bashrc

Now, back on your machine, access the application folder in the terminal and run the Capistrano command below to create config/secrets.yml on the production server:

$ cap production setup

All done! Now it's time to configure Capistrano to run a migration.

Configure Capistrano to Perform a Database Migration

Now it's time to configure Capistrano to run database-related commands.

The capistrano-rails gem already included in your Gemfile can be configured to perform a migration on each deployment. We just need to import it into Capfile:

# Capfile
require "capistrano/rails/migrations"

But if you want to run the seeds on deployment, you need to create a new task to run after the migration:

# config/deploy.rb

namespace :deploy do
  desc "Run seed"
  task :seed do
    on roles(:all) do
      within current_path do
        execute :bundle, :exec, 'rails', 'db:seed', 'RAILS_ENV=production'
      end
    end
  end

  after :migrating, :seed
end

With that, your app is finally ready to be deployed!

Start Deployment of Your Ruby on Rails App

Let's see how to perform a deployment from our local machine by directly updating our server to the new version of our application.

When you execute a deployment command, Capistrano will connect to your server. From there, Capistrano will try to clone the code from the repository defined in the configuration file (config/deploy.rb). Then other tasks will be performed, following the deployment flow.

Capistrano's deploy:check command validates that the Git configuration is alright and that Capistrano has correct access to the directories that will be used in the deployment.

To use it, pass the environment. In this case, we are using production:

$ cap production deploy:check

If everything is ok with the configuration, you can start your deployment to production:

$ cap production deploy

In addition, you can check all available tasks in Capistrano with the command:

$ cap --tasks

Now, in our final step, let's integrate our Ruby on Rails application with AppSignal and start monitoring it.

How to Integrate AppSignal with Capistrano and Your Rails App

AppSignal is a monitoring tool, so you might wonder why it's included in this article. That is a valid question, as monitoring is not directly related to deployments.

That said, AppSignal is a valuable tool when it comes to monitoring your Ruby on Rails application and keeping track of deployments in each environment. So let's see how we can set up AppSignal for your app.

You will need an AppSignal account, which you can create on AppSignal's sign-up page. Pick Ruby as your language and follow the steps to install AppSignal in your application.

Once installed, a file will be created to configure AppSignal. What's important here is to define the revision — information that will be checked after deployment to see if a new version of an application has been deployed. In this case, we will use the Git log as revision information to ensure that each new code deployment will notify AppSignal.

# config/appsignal.yml

production:
  <<: *defaults
  active: true
  revision: "<%= `git log --pretty=format:'%h' -n 1` %>"

It is also good practice to export AppSignal environment variables to your production server (especially the API key, so as not to keep it in the AppSignal configuration file).

export APPSIGNAL_PUSH_API_KEY=XXX

And now we can rerun the deployment. If everything is set up correctly, you will see a message like this at the end of the deployment:

Notifying AppSignal of deploy with: revision: ee5e626fd31613ef068873f9cddb5f8c91538396, user: monteirobrena
AppSignal has been notified of this deploy!

You will now be able to see your application in AppSignal! 🎉

And information about any deployments:

Visit AppSignal's deployment documentation page to learn more about deployment integration and other features available for Ruby on Rails applications.

Wrap Up and Next Steps

In this post, we explored how to use Capistrano to deploy your Ruby on Rails app. We first added Capistrano to an app, then configured and deployed it, before finally setting up monitoring with AppSignal.

If you'd like to explore further, you can configure Capistrano to run from an integration connected to your repository's pipeline. Tools like Bitbucket, GitHub, and GitLab provide settings to manage this process and can be used in conjunction with Capistrano.

Happy coding!

P.S. If you'd like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!

DEV Community: Brena Monteiro

Diving into Custom Exceptions in Ruby

A Quick Side-Note

How to Rescue an Exception with Ruby

Adding Additional Information to the Ruby Exception

Extending an Exception in Ruby

Wrapping Up and Next Steps

Improve Code in Your Ruby Application with RubyCritic

Why Choose RubyCritic for Your Ruby on Rails Application?

Internal Dependencies in RubyCritic

Reek: Detect Code Smells in Ruby

Flay: Check for Ruby Code Duplication

Flog: Examine Your Code Complexity in Ruby

Other RubyCritic Dependencies

Using RubyCritic for Your Ruby on Rails App

The Overview in RubyCritic

Code Report

Smells Report

Coverage Report

Wrap Up

Debugging in Ruby with AppSignal

Integrate Your Ruby App with AppSignal

Log Options

Ignore Your Ruby App's Predicted Errors in AppSignal

ignore_errors

ignore_actions

ignore_namespace

Configure in Your Ruby App

Debugging Exceptions in Ruby with AppSignal

Wrap Up and Next Steps

Deploy Your Ruby on Rails App Using Capistrano

Why Choose Capistrano for Your Ruby on Rails App?

Adding Capistrano to Your Ruby on Rails App

Server Configuration with Capistrano for Your Rails App

Adding capistrano-rvm Gem

Set Up Your Server Configuration

Set Up capistrano-secrets-yml Gem for Your Rails App

Configure Capistrano to Perform a Database Migration

Start Deployment of Your Ruby on Rails App

How to Integrate AppSignal with Capistrano and Your Rails App

Wrap Up and Next Steps

`ignore_errors`

`ignore_actions`

`ignore_namespace`

Adding `capistrano-rvm` Gem

Set Up `capistrano-secrets-yml` Gem for Your Rails App