> ## Documentation Index
> Fetch the complete documentation index at: https://launchdarkly-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Ruby SDK reference

> This topic documents how to get started with the server-side Ruby SDK, and links to reference information on all of the supported features.

> For the complete documentation index, see [llms.txt](/llms.txt). For the full documentation snapshot, see [llms-full.txt](/llms-full.txt).

## Overview

This topic documents how to get started with the server-side Ruby SDK, and links to reference information on all of the supported features.

<Note title="SDK quick links">
  LaunchDarkly's SDKs are open source. In addition to this reference guide, we provide source, API reference documentation, and sample applications:
</Note>

| Resource | Location |
| - | - |
| SDK API documentation | [SDK API docs](https://launchdarkly.github.io/ruby-server-sdk/) |
| Supported SDK Versions | [Ruby server SDK](../concepts/supported-versions#ruby-server-sdk) |
| GitHub repository | [ruby-server-sdk](https://github.com/launchdarkly/ruby-server-sdk) |
| Sample applications | [Ruby](https://github.com/launchdarkly/hello-ruby) ,  [Rails with bootstrapping](https://github.com/launchdarkly/hello-bootstrap-rails) |
| Published module | [RubyGems](https://rubygems.org/gems/launchdarkly-server-sdk) |

<Note title="SDK version compatibility">
  The LaunchDarkly Ruby SDK, version 8.0 and higher, is compatible with Ruby 3.0.

  The LaunchDarkly Ruby SDK, version 7.x, is compatible with Ruby 2.7 and higher.

  Prior to version 7.0, the LaunchDarkly Ruby SDK also supported Ruby 2.5 and 2.6.
</Note>

## Get started

After you complete the [Get started process](/home/getting-started), follow these instructions to start using the LaunchDarkly SDK in your Ruby application.

### Install the SDK

First, install the LaunchDarkly SDK as a dependency in your application using your application's dependency manager. Refer to the [SDK releases page](https://github.com/launchdarkly/ruby-server-sdk/releases) to identify the latest version if you want to depend on a specific version.

If you are using Bundler, you can add `gem "launchdarkly-server-sdk"` to your Gemfile and run `bundle install`. Otherwise, you can install the gem directly:

<CodeGroup>
  ```bash title="Shell" theme={null}
      gem install launchdarkly-server-sdk
  ```
</CodeGroup>

Next, import the LaunchDarkly client in your application code. This step may not be necessary if you are using a framework that automatically loads all dependencies, as Rails does.

Here's how:

<CodeGroup>
  ```ruby title="Ruby" theme={null}
      require 'ldclient-rb'
  ```
</CodeGroup>

<Note title="The Ruby SDK uses an SDK key">
  The Ruby SDK uses an SDK key. Keys are specific to each project and environment. They are available from **Project settings**, on the **Environments** list. To learn more about key types, read [Keys](/sdk/concepts/client-side-server-side#keys).
</Note>

### Initialize the client

After you install and import the SDK, create a single, shared instance of `LDClient`. Specify your SDK key here to authorize your application to connect to a particular environment within LaunchDarkly.

<Warning title="LDClient must be a singleton">
  It's important to make `LDClient` a singleton for each LaunchDarkly project. The client instance maintains internal state that allows LaunchDarkly to serve feature flags without making any remote requests. Do not instantiate a new client with every request.

  If you have multiple LaunchDarkly projects, you can create one `LDClient` for each. In this situation, the clients operate independently. For example, they do not share a single connection to LaunchDarkly.
</Warning>

Here's how:

<CodeGroup>
  ```ruby title="Ruby" theme={null}
      client = LaunchDarkly::LDClient.new("YOUR_SDK_KEY")
  ```
</CodeGroup>

<Warning title="Worker-based servers require specific setup">
  The Ruby SDK uses multiple background threads to operate correctly. If the SDK is deployed to an environment which forks from the main process, the SDK may not operate as expected. To learn more about this problem and how to fix it, refer to [Considerations with worker-based servers](#considerations-with-worker-based-servers), below.
</Warning>

### Considerations with worker-based servers

The LaunchDarkly SDK relies on multiple threads to operate correctly. These threads provide essential functionality, including delivering flag updates and sending event data.

If the main process which instantiated the SDK is itself forked, the SDK will still evaluate flags, but it will be unable to receive changes to those flags in that child process. This is because threads do not survive the forking process in Ruby.

The good news is the LaunchDarkly SDK *is* compatible with process-forking servers. However, there are a few considerations:

1. You should initialize a new client before the forking process.
2. After you have forked the worker process, you can call `postfork` to reinitialize the client. This way, your client will accurately reflect flag changes in the forked thread.

Here's how:

<CodeGroup>
  ```ruby title="Ruby SDK v8.11+" theme={null}
      # 1. Create the client before forking.
      client = LaunchDarkly::LDClient.new("YOUR_SDK_KEY")

      # 2. From the newly forked process, reinitialize the client by calling `postfork`.
      # Examples for specific servers are shown below.
      client.postfork
  ```
</CodeGroup>

Any configuration that you provide to the SDK must survive the forking process independently. We recommend that you add any [listeners](/sdk/features/monitoring#ruby) or [hooks](/sdk/features/hooks#ruby) after the `postfork` call, unless you are certain they can survive the forking process.

If you are using the [Relay Proxy](/sdk/relay-proxy), you must use Relay Proxy v8.11 or later to use `postfork`.

To learn more about the specific configuration options available in this SDK, read [`Config`](https://launchdarkly.github.io/ruby-server-sdk/LaunchDarkly/Config). To learn more about the `postfork` reinitialization, read [`postfork`](https://launchdarkly.github.io/ruby-server-sdk/LaunchDarkly/LDClient.html#postfork-instance_method).

<Accordion title="Expand Using a Rails application">
  #### Using a Rails application

  To use LaunchDarkly in a Rails application, initialize the client in `config/initializers/launchdarkly.rb` as shown below. This provides access to the `LDClient` globally in the Rails application and through the Rails console.

  If the web server running Rails does not fork workers from this process, no further configuration is required. In all other cases, once the worker process has forked, the `postfork` method of the `LDClient` should be called. To learn more about your specific server, refer to the example server integrations below.

  <CodeGroup>
    ```ruby title="Ruby" theme={null}
          Rails.configuration.client = LaunchDarkly::LDClient.new("YOUR_SDK_KEY")
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Expand Using Puma">
  #### Using Puma

  If you use the [Puma](https://github.com/puma/puma) web server, we recommend reinitializing the client in `on_worker_boot`:

  <CodeGroup>
    ```ruby title="Ruby Puma initialization with Rails" theme={null}
          on_worker_boot do
            Rails.configuration.client.postfork
          end
    ```

    ```ruby title="Ruby Puma initialization" theme={null}
          client = LaunchDarkly::LDClient.new("YOUR_SDK_KEY")

          on_worker_boot do
            client.postfork
          end
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Expand Using Spring">
  #### Using Spring

  To use LaunchDarkly with the Rails application preloader [Spring](https://github.com/rails/spring), we recommend using an `after_fork` callback in the `config/spring.rb` file to reinitialize the client:

  <CodeGroup>
    ```ruby title="Ruby Spring initialization with Rails" theme={null}
          Spring.after_fork do
            Rails.configuration.client.postfork
          end
    ```

    ```ruby title="Ruby Spring initialization" theme={null}
          client = LaunchDarkly::LDClient.new("YOUR_SDK_KEY")

          Spring.after_fork do
            client.postfork
          end
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Expand Using Unicorn">
  #### Using Unicorn

  If you use [Unicorn](https://www.rubydoc.info/gems/unicorn), specify an `after_fork` hook in your unicorn.rb config file:

  <CodeGroup>
    ```ruby title="Ruby Unicorn initialization with Rails" theme={null}
          after_fork do |server,worker|
            Rails.configuration.client.postfork
          end
    ```

    ```ruby title="Ruby Unicorn initialization" theme={null}
          client = LaunchDarkly::LDClient.new("YOUR_SDK_KEY")

          after_fork do |server,worker|
            client.postfork
          end
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Expand Using Passenger">
  #### Using Passenger

  If you use the [Passenger](https://www.phusionpassenger.com/library/indepth/ruby/spawn_methods/#smart-spawning-hooks) web server, we recommend reinitializing the client in `config.ru`, or from any code called while loading `config.ru`:

  <CodeGroup>
    ```ruby title="Ruby Passenger initialization with Rails" theme={null}
          if defined?(PhusionPassenger)
            PhusionPassenger.on_event(:starting_worker_process) do |forked|
              Rails.configuration.client.postfork
            end
          end
    ```

    ```ruby title="Ruby Passenger initialization" theme={null}
          client = LaunchDarkly::LDClient.new("YOUR_SDK_KEY")

          if defined?(PhusionPassenger)
            PhusionPassenger.on_event(:starting_worker_process) do |forked|
              client.postfork
            end
          end
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Expand Using httplog">
  #### Using httplog

  If you are using the Rails `httplog` library, you should include `launchdarkly.com` in the `url_blacklist_pattern` attribute of `httplog`'s configuration.

  By default, the Rails `httplog` library buffers the entire response to a request. However, in the LaunchDarkly SDKs, the streaming request remains open. Therefore, the `httplog` library intercepts the request but never returns the response from LaunchDarkly indicating that initialization is complete. This means the Ruby SDK may not complete initialization and also may not log an error. If your application makes flag evaluations before the SDK initialization is complete, you may receive the message: `[LDClient] Client has not finished initializing; feature store unavailable, returning default value`.

  When you include `launchdarkly.com` in the `url_blacklist_pattern` attribute of `httplog`'s configuration, then `httplog` will not intercept the response, and SDK initialization will complete. This lets you use flags as expected.

  To learn more, read the [`httplog` Configuration documentation](https://www.rubydoc.info/gems/httplog/1.1.1#configuration).
</Accordion>

### Evaluate a context

You can use `client` to check which variation a particular context will receive for a given feature flag. To learn more, read [Evaluating flags](/sdk/features/evaluating) and [Flag evaluation reasons](/sdk/features/evaluation-reasons). For more information about how contexts are specified, read [Context configuration](/sdk/features/context-config).

Here's how:

<CodeGroup>
  ```ruby title="Ruby SDK v7.0+" theme={null}
      context = LaunchDarkly::LDContext.with_key("example-context-key")
      show_feature = client.variation("example-flag-key", context, false)
      if show_feature
        # application code to show the feature
      else
        # the code to run if the feature is off
      end
  ```
</CodeGroup>

## Shut down the client

Shut down the client when your application terminates. This frees the resources the worker threads were using and provides an explicit signal for the Ruby SDK to send the remaining event data back to LaunchDarkly. To learn more, read [Shutting down](/sdk/features/shutdown#ruby).

## Supported features

This SDK supports the following features:

* [Anonymous contexts and users](/sdk/features/anonymous#ruby)
* [Big segments](/sdk/features/big-segments#ruby)
* [Configuration](/sdk/features/config#ruby), including
  * [Application metadata configuration](/sdk/features/app-config#ruby)
  * [Migration configuration](/sdk/features/migration-config#ruby)
  * [Service endpoint configuration](/sdk/features/service-endpoint-configuration/server-side#ruby)
* [Context configuration](/sdk/features/context-config/server-side#ruby)
* [Data saving mode](/sdk/features/data-saving-mode#ruby)
* [Evaluating flags](/sdk/features/evaluating#ruby)
* [Flag evaluation reasons](/sdk/features/evaluation-reasons/server-side#ruby)
* [Flushing events](/sdk/features/flush#ruby)
* [Getting all flags](/sdk/features/all-flags#ruby)
* [Hooks](/sdk/features/hooks#ruby)
* [Identifying and changing contexts](/sdk/features/identify#ruby)
* [Logging configuration](/sdk/features/logging#ruby)
* [Migrations](/sdk/features/migrations#ruby)
* [Monitoring SDK status](/sdk/features/monitoring#ruby)
* [Offline mode](/sdk/features/offline-mode#ruby)
* [OpenTelemetry](/sdk/features/opentelemetry-server-side#ruby)
* [Private attributes](/sdk/features/private-attributes/server-side#ruby)
* [Reading flags from a file](/sdk/features/flags-from-files#ruby)
* [Relay Proxy configuration](/sdk/features/relay-proxy-configuration)
  * [Using proxy mode](/sdk/features/relay-proxy-configuration/proxy-mode#ruby)
  * [Using daemon mode](/sdk/features/relay-proxy-configuration/daemon-mode#ruby)
* [Secure mode](/sdk/features/secure-mode#ruby)
* [Sending custom events](/sdk/features/events#ruby)
* [Shutting down](/sdk/features/shutdown#ruby)
* [Storing data](/sdk/features/storing-data#ruby)
* [Subscribing to flag changes](/sdk/features/flag-changes#ruby)
* [Test data sources](/sdk/features/test-data-sources#ruby)
* [Web proxy configuration](/sdk/features/web-proxy#ruby)