Occson and Ruby on Rails

Tomasz Kowalewski | July 10, 2021

Configuration - a recurring nightmare for many developers and devops alike. How do we provide configuration variables for a Ruby on Rails application? With occson, it’s easy.

First things first: let’s create a new Ruby on Rails app. We’ll call it envie - since it’ll show us its environment variables. If this is nothing new to you, feel free to skip to the juicy part!

$: rails new envie

Let’s also create a controller in app/controllers/home_controller.rb:

class HomeController < ApplicationController
  def index

And a view in app/views/home/index.html.erb:

<% ENV.each do |key, value| %>
<p><%= key%>:<%= value %></p>
<% end %>

We’ll set up our routes in the usual place - config/routes.rb:

Rails.application.routes.draw do
  root to: 'home#index'

We need to start our application server,

$: bin/rails s

And visit http://localhost:3000/.

Our Ruby on Rails app will now show us its environment variables.

Now let’s pretend that after some time spent developing it, our app turns out to need a certain configuration setting. We’ll of course provide that through an environment variable, for maximum flexibility. We’ll call this variable FOO.

If we’re just running locally, we can just provide this variable on the command line:

$: FOO=1 bin/rails s

If we navigate to the app again, we’ll see FOO: 1. Success!

Well… for now. But what if our app needs, say, twenty seven environment variables? We definitely don’t want to be passing all that to the application server command!

This is where occson comes in. Like a superhero to the rescue, it configures our application on demand.

Let’s set up an account on http://occson.com.


After inputting our e-mail address we’ll get a message with a sign-in link. Occson uses a passwordless sign-in method - it’s like magic, but better.

To start working with occson, we’ll need a workspace.


To communicate with occson from code, we’ll need an access token.


Time to create a configuration file that we will provide to our application. We can create it two ways. Through a browser:


or through the command line. Since that’s where us developers live, let’s see how that’s done.

First, just install the gem:

$: gem install occson

We create the configuration file locally:

echo "FOO=1" > .env

And then we push it to occson:

$: occson cp --access-token=1c442124a1f537b82e5f --passphrase=kdj28duejd .env occson://0.1.0/.env

“That’s cool for an example,” you might say, “but there’s no way I’m just pushing my production variables somewhere, there’s super-secret stuff in there!” That’s where more occson magic comes in.

The file you upload is encrypted right on your machine (yes, even if you’re using the web interface)! The document passphrase is the secret that you have, and we don’t. You can read our docs to see how it’s done. And if you’d rather see the code, check out our gem’s reference implementation on GitHub.

With that out of the way, let’s integrate occson into our app. It’s as simple as dropping the occson gem in the Gemfile:

gem 'occson'

bundle it all up,


And we’ll create an initializer in config/initializers/001_occson.rb to fetch and set up our environment variables.

require 'occson'

source = 'occson://0.1.0/.env'
access_token = ENV.fetch('OCCSON_ACCESS_TOKEN')
passphrase = ENV.fetch('OCCSON_PASSPHRASE')

document = Occson::Document.new(source, access_token, passphrase).download

document.split("\n").each do |line|
  key, value = line.split("=", 2)

  ENV.store(key, value)

When we now run the application server,

OCCSON_ACCESS_TOKEN=1c442124a1f537b82e5f OCCSON_PASSPHRASE=kdj28duejd bin/rails s

our app shows the FOO variable correctly!