Redis

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

  cache1:
    type: redis
    name: custom_name
/Boxfile

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:

CACHE1_HOST, CACHE1_PORT
CACHE2_HOST, CACHE2_PORT
etc.

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

  web1:
    type: php
    php_extensions:
      - redis
   
  cache1:
    type: redis
/Boxfile

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.

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.

PHP

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

  web1:
    type: php
    php_extensions:
      - redis
    php_session_save_handler: redis
    php_session_save_path: "tcp://${CACHE1_HOST}:${CACHE1_PORT}"
   
  cache1:
    type: redis
/Boxfile

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.