An stunnel buildpack for Redis
Switch branches/tags
Nothing to show
Clone or download
Pull request Compare This branch is 16 commits ahead, 5 commits behind peterfication:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
README.md

README.md

Heroku buildpack: Redis

This is a Heroku buildpack that allows an application to use an stunnel to connect securely to Heroku Redis. It is meant to be used in conjunction with other buildpacks.

Usage

First, ensure your Heroku Redis addon is using a production tier plan. SSL is not available when using the hobby tier.

Then set this buildpack as your initial buildpack with:

$ heroku buildpacks:add -i 1 heroku/redis

Then confirm you are using this buildpack as well as your language buildpack like so:

$ heroku buildpacks
=== frozen-potato-95352 Buildpack URLs
1. https://github.com/heroku/heroku-buildpack-redis.git
2. heroku/python

For more information on using multiple buildpacks check out this devcenter article.

Next, for each process that should connect to Redis securely, you will need to preface the command in your Procfile with bin/start-stunnel. In this example, we want the web process to use a secure connection to Heroku Redis. The worker process doesn't interact with Redis, so bin/start-stunnel was not included:

$ cat Procfile
web:    bin/start-stunnel bundle exec unicorn -p $PORT -c ./config/unicorn.rb -E $RACK_ENV
worker: bundle exec rake worker

We're then ready to deploy to Heroku with an encrypted connection between the dynos and Heroku Redis:

$ git push heroku master
...
-----> Fetching custom git buildpack... done
-----> Multipack app detected
=====> Downloading Buildpack: https://github.com/heroku/heroku-buildpack-redis.git
=====> Detected Framework: stunnel
       Using stunnel version: 5.02
       Using stack version: cedar
-----> Fetching and vendoring stunnel into slug
-----> Moving the configuration generation script into app/bin
-----> Moving the start-stunnel script into app/bin
-----> stunnel done
=====> Downloading Buildpack: https://github.com/heroku/heroku-buildpack-ruby.git
=====> Detected Framework: Ruby/Rack
-----> Using Ruby version: ruby-2.2.2
-----> Installing dependencies using Bundler version 1.7.12
...

Configuration

The buildpack will install and configure stunnel to connect to REDIS_URL over a SSL connection. Prepend bin/start-stunnel to any process in the Procfile to run stunnel alongside that process.

Stunnel settings

Some settings are configurable through app config vars at runtime:

  • STUNNEL_ENABLED: Default to true, enable or disable stunnel.
  • STUNNEL_LOGLEVEL: Default is notice, set to info or debug for more verbose log output.

Multiple Redis Instances

If your application needs to connect to multiple Heroku Redis instances securely, this buildpack will automatically create an Stunnel for each color Heroku Redis config var (HEROKU_REDIS_COLOR) and the REDIS_URL config var. If you have Redis urls that aren't in one of these config vars you will need to explicitly tell the buildpack that you need an Stunnel by setting the REDIS_STUNNEL_URLS config var to a list of the appropriate config vars:

$ heroku config:add REDIS_STUNNEL_URLS="CACHE_URL SESSION_STORE_URL"

Using the edge version of the buildpack

The heroku/redis buildpack points to the latest stable version of the buildpack published in the Buildpack Registry. To use the latest version of the buildpack (the code in this repository), run the following command:

$ heroku buildpacks:add https://github.com/heroku/heroku-buildpack-redis

Troubleshooting

Redis URLs without a username

This buildpack assumes that every URL is with username and password. As Redis does not support usernames but only passwords you may encounter a problem here. Just invent a username and put it in your URL.

redis://:password@example.com:6379
=> Invent username (here "h")
redis://h:password@example.com:6379

Choose the right port

This buildpack assumes that you use the non SSL port in your REDIS_URL variable. So it adds 1 to this port for the SSL port. So if your SSL port is 6380 you have to set it to 6379 in your REDIS_URL variable.