Last Updated October 2014

Redis is an "open source, advanced key-value store" that makes for an extremely powerful caching mechanism, queuing engine, or in-memory database. After reading this doc, you will be familiar with:

  • Adding a Redis service to your app
  • Connecting to and using your Redis service

Creating a Redis Service

Redis services can be created through both your dashboard and your Boxfile

Through the Dashboard

To create a Redis service through your dashboard, click on "New Service," then click the Redis icon.

You're given the option to name your Redis service and select which Redis version you'd like use. If no name is provided, we will create one for you. Click "Create Service" to begin provisioning your Redis cache.

Through the Boxfile

To create a Redis service through your Boxfile, include a cache service with the type set to "redis". You can provide a name for your service if you'd like. If you don't provide one, we will generate one for you.

Creating a Redis Service from Your Boxfile YAML

    type: redis
    name: custom_name

On your next deploy, your Redis service will be created.

Configuring Redis

All environment configuration is handled in the Boxfile. The Redis Settings in the Boxfile doc walks through all of the configurable Redis options.

Connecting to Redis

Because applications vary widely in how they connect to Redis, it's hard to give you a generic code example of how to connect to your Redis service. What is uniform is the need for a Host and Port to connect to. You can include these in your codebase by either hard-coding them, or by including the auto-generated environment variables.

Hard Coding the Connection Credentials

After the service has been created, you can find the proper connection credentials for your Redis service in your App Dashboard. Click on your service to expand the service options. Open the "Connection" tab.

Once these credentials are in the correct location in your source code, you should be good to go.

Using Environment Variables

Whenever a Redis service is created on Pagoda Box, we automatically generate environment variables for each of the necessary connection credentials. This allows you to include the proper connection credentials in your codebase before the service is even created. It also allows you to obscure your connection credentials by never actually having to store them in your repo.

The naming convention is as follows:


Be Sure to Include Necessary Extensions

If you're connecting to Redis from PHP service, be sure to include the "redis" php_extension in your web/worker service Boxfile config. This extension is required for PHP to connect to Redis.

Enabling Extensions in Your Boxfile YAML

    type: php
      - redis
    type: redis

Managing Your Redis Service

Your Redis service can be managed remotely through the use of the Pagoda Tunnel or by SSH'ing into a web service and interacting with Redis from there. The SSH Access doc walks through how.

Below is an example of opening a tunnel using the Pagoda CLI, then using telnet to connect to Redis using the connection credentials provided in the dashboard.

Tunnel & Connect to Your Redis Service Terminal

  # Open a tunnel using the pagoda cli
  $ pagoda tunnel cache1

  Tunnel established, use the following credentials to connect:

  Host      : localhost
  Port      : 6379
  Username  :
  Password  :
  Database  : gopagoda

  (note : ctrl-c To close this tunnel)

  # In another shell session with the tunnel still open,
  # connect to redis through the tunnel using the redis-cli

  $ redis-cli -h localhost -p 6379

Once the Redis CLI has connected, you can run any of the Redis commands.

Making Redis Redundant

Data stored in Redis can be incredibly important and ideally will always be available. Adding redundancy to your Redis service is the best way to ensure your data is always available. To make Redis redundant, use the "redundant" topology when creating your database.

After your Redis service is created, the topology can be changed in your dashboard.

With the Redundant topology, a second Redis instance is provisioned with master-slave replication between the two instances. If the primary instance every fails or becomes unresponsive, the second will act as a hot failover and take over handling requests until the primary instance can be repaired and/or restarted.

Small Potential for Data Loss

Because of Redis' asynchronous persistence model, there is a small chance that data could be lost in the failover process. If an instance goes offline or stops responding before data has persisted to disk and synced, that data will be lost.

In all of our testing as well as in our production use of redundant Redis, we have never lost data in the failover process.

Using Redis as a Session Store

Redis is a great tool for storing sessions and it's incredibly easy to use your Redis as a session store on Pagoda Box. It's all handled in the Boxfile.


To use Redis as a PHP session store, you need to set your php_session_save_handler and php_session_save_path in your Boxfile. Also be sure to include the redis PHP extension. This method will only work with native PHP sessions. If your app is using a custom session handler, you'll have to configure the Redis connection there.

Redis PHP Session Handler in the Boxfile YAML

    type: php
      - redis
    php_session_save_handler: redis
    php_session_save_path: "tcp://${CACHE1_HOST}:${CACHE1_PORT}"
    type: redis

You can use the Pagoda Tunnel and the Redis-CLI to connect to and manage your Redis service.

If you have any questions, suggestions, or corrections, let us know.