Flipper Cloud Documentation

What is this?

Flipper Cloud is a platform for feature flipping, which in its simplest form is named conditionals used to control code execution. The primary benefit of feature flags compared to fixed conditionals is the ability to change a feature's state (enabled or disabled) from outside the running program.

We make it easy to...

Manage all your projects in one place. Rather than having feature flags setup in separate or unique ways for each application or micro-service, we can centralize feature flag control, access and auditing for your entire organization.
Give non-technical staff the power to release code. Engineers setup the conditionals in the code, but anyone can enable or disable them using targeting as wide as a group or % of users to as narrow as a single user or random moment in time.
Get code into production faster. Once a feature flag is in place and protecting your new code, you can ship the new code to production and avoid long lived version control branches (and the hassle that comes with keeping them up to date and merging/deploying them safely).
Safely isolate new and existing code. Turning off a feature flag is always faster than a rollback. Similarly, sometimes you just want to turn something non-critical off and go back to bed. We make it a single button click (and include an audit log of every change).
Slowly rollout new features. By enabling a feature for a small percentage of users and slowly increasing, you can gain confidence in a new application feature and avoid a thundering herd of users eager to check it out.

How does it work?

We have a beautiful, web interface for managing your projects, environments and features. Additionally, we expose a simple HTTP API along with a client library that takes only a few minutes to integrate into your application.

When you create a project, it comes preloaded with development and production environments to get you up and running quickly, but we support as many other environments as necessary (e.g. staging, smoke, per engineer laptop, Heroku review app, or whatever you can dream up).

Basic Setup

Flipper.configure do |config|
  config.default { Flipper::Cloud.new("<your-token-here>") }
end

if Flipper.enabled?(:billing)
  # get paid
else
  # wish you were getting paid
end

Open Source

Flipper Cloud is built on top of jnunemaker/flipper. The Flipper Cloud client library is a pre-configured version of the Flipper HTTP adapter. The HTTP adapter communicates with the Flipper API mounted in our application. If most of the bits that make up Flipper Cloud are open source, why not tack them all together on your own and self-host? The simple answer is that the bits that are open source are the easy ones. They will get you up and running, but do not address the harder parts, such as permissions, auditing and analytics.

As Garrett Dimon put it so well in the Choose Vendors Wisely chapter of Starting and Sustaining:

I’ll go a step further and suggest that you don’t use self-hosted applications when hosted services are available. While it may seem simple on the surface, maintaining even one–let alone a handful–of self-hosted tools can quickly become a distraction. Security updates, availability, and upgrades are all extra work that take you away from focusing on your product. Self-hosted solutions may be worthwhile for your business in the long term, but if you have a small team, they’re one more burden that can weigh you down.

Organizations

Organizations allow you to group projects for permissions and billing purposes. You can belong to one or more organizations. Each organization can have as many projects and members as necessary. Organization members are automatically granted access to all projects owned by the organization.

Projects

Projects allow you to manage many different applications and services under one organization. Each project has its own environments and features. All members of the owning organization are automatically granted access to the project. Additionally, you can grant access for people directly to one or more projects.

Environments

Environments allow you to model your development lifecycle and vary feature enablement depending on where the code is executed (e.g. from local development to staging to production). Production and development environments are automatically created for each project, but you are free to add any others as needed.

All feature enablements are scoped to environment, but by default mirror production. This means that if a feature is enabled in production, it is enabled in all environments, unless that environment has explicitly overridden it (e.g. disabled in production, but enabled in local development for engineers).

API Tokens

Each environment can have one or more API tokens as well, allowing for rotation without impacting currently in use tokens. You can generate a new token, update your application configuration to the new token, and archive the old token to rotate the token.

Features

Features are the heart of Flipper Cloud. They allow you to control code execution based on a few different types of enablement.

1. Boolean

All on or all off. Think top level things like :stats, :search, :logging, etc. Also, an easy way to release a new feature, as once a feature is boolean enabled it is on for every situation.

Boolean Example

user = User.find(...)

Flipper.enabled?(:search) # false
Flipper.enabled?(:search, user) # false

Flipper.enable(:search)

Flipper.enabled?(:search) # true
Flipper.enabled?(:search, user) # true

2. Group

Turn on feature based on the return value of block. Super flexible way to turn on a feature for multiple things (users, people, accounts, etc.) as long as the thing returns true when passed to the block.

Group Example

user  = User.find(...) # user who returns true for admin? method
admin = User.find(...) # user who returns true for admin? method

# Define the block that will return true or false based on actor. Registers a
# group named admins which saves the block to be called later.
Flipper.register(:admins) do |actor, context|
  actor.respond_to?(:admin?) && actor.admin?
end

Flipper.enabled?(:documentation, user) # false
Flipper.enabled?(:documentation, admin) # false

# Enable the block named admins which means future enabled? checks will see if
# the passing the actor to the block returns true.
Flipper.enable_group(:documentation, :admins)

# When user is passed to enabled?, Flipper knows that the admins group is
# enabled. It executes the registered block above, yielding user. user responds
# to admin?, but admin? returns false, which means the feature will not be
# enabled for the user (true && false == false).
Flipper.enabled?(:documentation, user) # false

# Same as the previous check, but this time admin? returns true for the user
# which means the feature will be enabled (true && true == true).
Flipper.enabled?(:documentation, admin) # true

There is no requirement that the thing yielded to the block be a user model or whatever. It can be anything you want, therefore it is a good idea to check that the thing passed into the group block actually responds to what you are trying to do in the register proc.

3. Actor

Turn feature on for individual thing. Think enable feature for someone to test or for a buddy. The only requirement for an individual actor is that it must respond to flipper_id.

Actor Example

user = User.find(...)
other_user = User.find(...)

Flipper.enabled?(:verbose_logging) # false
Flipper.enabled?(:verbose_logging, user) # false

Flipper.enable_actor(:verbose_logging, user)

Flipper.enabled?(:verbose_logging) # false
Flipper.enabled?(:verbose_logging, user) # true
Flipper.enabled?(:verbose_logging, other_user) # false

The key is to make sure you do not enable two different types of objects for the same feature. Imagine that user has a flipper_id of 6 and group has a flipper_id of 6. Enabling search for user would automatically enable it for group, as they both have a flipper_id of 6.

The one exception to this rule is if you have globally unique flipper_ids, such as UUIDs. If your flipper_ids are unique globally in your entire system, enabling two different types should be safe. Another way around this is to prefix the flipper_id with the class name like this:

class User
  def flipper_id
    "User;#{id}"
  end
end

class Group
  def flipper_id
    "Group;#{id}"
  end
end

4. Percentage of Actors

Turn this on for a percentage of actors (think user, member, account, group, whatever). Consistently on or off for this user as long as percentage increases. Think slow rollout of a new feature to a percentage of things.

Percentage of Actors Example

user = User.find(...) # responds to flipper_id method call

Flipper.enable_percentage_of_actors(:new_design, 25)

# returns true or false consistently for the same enabled percentage and actor
Flipper.enabled?(:new_design, user)

Percentage of actors also takes into account the feature name to ensure that the same actors are not granted access first to every feature.

5. Percentage of Time

Turn this on for a percentage of time. Think load testing new features behind the scenes and such.

Percentage of Time Example

user = User.find(...)

Flipper.enable_percentage_of_time(:dark_ship_new_feature, 25)

# returns true for ~25% of the enabled? calls irregardless of the actor provided
Flipper.enabled?(:dark_ship_new_feature)
Flipper.enabled?(:dark_ship_new_feature, user)

Percentage of time is not a good idea for enabling new features in a UI. Most often you'll use percentage of actors, but there are definitely times when I have found percentage of time to be very useful.

Getting Started

Setting up Flipper takes only a few minutes. Follow the guide below or let us know if you would prefer to have us do it for you. For the moment, Flipper Cloud only supports ruby applications. If there is another language you would like to see support for, we would love to know.

Ruby on Rails

In addition to the steps outlined below, we have a fully functional example Rails application for you to peruse.

Step 1. Add Flipper to your Gemfile

Gemfile

# Required: This is what talks to flippercloud.io on your behalf.
gem "flipper-cloud", "~> 0.18.0"

# Optional: This can be any other Flipper adapter (e.g. redis, mongo, etc.). It
# defaults to in memory, but we highly recommend something persistent, like
# the active record adapter.
gem "flipper-active_record", "~> 0.18.0"

Run bundle to install.

$ bundle

Step 2. Configure Flipper in an Initializer

config/initializers/flipper.rb

require "flipper/cloud"
require "flipper/adapters/active_record"

Flipper.configure do |config|
  config.default do
    token = ENV.fetch("FLIPPER_TOKEN")

    Flipper::Cloud.new(token) do |cloud|
      # All Flipper reads in your app will go to this adapter. Whatever you use
      # as your local adpater, you'll need in your Gemfile as shown above.
      # Defaults to in memory.
      cloud.local_adapter = Flipper::Adapters::ActiveRecord.new
    end
  end
end

# Memoize Flipper adapter calls per request
require "flipper/middleware/memoizer"
Rails.configuration.middleware.use Flipper::Middleware::Memoizer, preload_all: true

Step 3. Run your App

The initializer in the previous step assumes that you will be using environment variables to configure flipper. We recommend using dotenv to manage these for you on your laptop. Below is a sample .env file:

.env

FLIPPER_TOKEN=<your-token-here>

Need Help?

We would be delighted to answer any questions or even setup a pairing session to help you get your application setup correctly. Shoot an email to support@flippercloud.io.