Last updated October 11, 2024

HTTP is a stateless protocol, but most applications need to preserve certain information across requests, such as login state or the contents of a shopping cart. This kind of state is usually stored in a session.

You can either store sessions on the client side in encrypted HTTP cookies or on the server side with a variety of persistence mechanisms. Both approaches have advantages and disadvantages, but this article describes how to reliably handle server-side sessions in Java applications on Heroku. All of the examples in this article use Heroku Key-Value Store (KVS) as the storage mechanism.

Why Use Key-Value Store to Store Sessions?

File-based session storage and in-memory storage are discouraged on Heroku because of the stateless nature of dynos and the need to scale them horizontally. In both file and in-memory storage, session data is lost on restart and cannot be shared between dynos. Furthermore, if sessions are stored local to a dyno, the next request from a user might end up on a different dyno, where the session information does not exist.

A KVS instance persists data across dyno restarts and can be shared between multiple dynos, which makes it an excellent solution for storing sessions. You can add a KVS instance to your app by running:

$ heroku addons:create heroku-redis

This populates a REDIS_URL config var on your app, which is ready to use with the strategies described in this article. Alternatively, you can use any of Heroku’s third-party Redis add-ons.

Storing Sessions with Tomcat Webapp Runner

Heroku’s recommended servlet container, Tomcat Webapp Runner, has built-in support for session storage with either Redis or Memcached. To use it with the Heroku Key-Value Store add-on, pass the --session-store redis option to your Webapp Runner JAR file by adding it to your Procfile like this:

web: java -jar target/dependency/webapp-runner.jar --session-store redis target/myapp.war

Alternatively, if you’re using either the heroku war:deploy or mvn heroku:deploy-war commands (and therefore do not have a Procfile), you can set this option as a config var by running:

$ heroku config:set WEBAPP_RUNNER_OPTS="--session-store redis"

Webapp Runner detects the REDIS_URL environment variable provided by the add-on and starts using it to store your application’s HTTP sessions.

Storing Sessions with Redisson

If you’re not using Webapp Runner, then you need a library like Redisson, a popular, high-performance Java client for Redis. It can be used for many different purposes, including session storage.

Redisson provides adapters for Tomcat and Spring. For other servers and frameworks, you need to use the Redisson API directly.

In all cases, you must create an org.redisson.config.Config object in your Java code like this:

String redisUriString = System.getenv("REDIS_URL");

URI redisUri = URI.create(redisUriString);

Config config = new Config();
SingleServerConfig serverConfig = config.useSingleServer()
          .setAddress(redisUriString)
          .setConnectionPoolSize(10)
          .setConnectionMinimumIdleSize(10)
          .setTimeout(5000);

if (redisUri.getUserInfo() != null) {
  serverConfig.setPassword(redisUri.getUserInfo().substring(redisUri.getUserInfo().indexOf(":")+1));
}

Then you can create a new RedissonClient instance using the Config object:

RedissonClient redisson = Redisson.create(config);

If you’re using Spring or Spring Boot, you also need the @EnableRedissonHttpSession annotation, as described in the Redisson documentation.

How you store objects with the client depends on how your framework or server works. The Redisson documentation has a number of examples and common patterns.

Other Options

There are many other clients and libraries that facilitate session store in both Redis and Memcached. They include:

• Jedis: a Java Redis client
• XMemcached: a Java Memcached client

You can also check the add-on provider documentation for Memcachier for examples of connecting to Memcached.