Installation

Add the Spring Boot Redis Rate Limiter starter to your project

Installation

Add the Spring Boot Redis Rate Limiter starter to your Maven or Gradle project. The starter includes auto-configuration that works out of the box with Spring Boot 3.x.

Requirements

Before installing, ensure your project meets these requirements:

Java 17+

Java 17 or higher is required

Spring Boot 3.x

Spring Boot 3.4.5 or compatible version

Redis

Redis instance accessible to your application

Add the dependency

Choose your build tool and add the appropriate dependency:

Maven

<dependency>
  <groupId>io.github.v4run-sharma</groupId>
  <artifactId>spring-boot-starter-redis-ratelimiter</artifactId>
  <version>1.0.1</version>
</dependency>

The starter uses Spring Boot’s dependency management, so you don’t need to specify versions for transitive dependencies like Spring Data Redis or Lettuce.

Configure Redis connection

The starter requires a Redis connection. Configure it using standard Spring Boot Redis properties:

application.yml

spring:
  data:
    redis:
      host: localhost
      port: 6379

Redis with authentication

If your Redis instance requires authentication:

application.yml

spring:
  data:
    redis:
      host: redis.example.com
      port: 6379
      password: your-redis-password
      ssl:
        enabled: true

Redis Cluster or Sentinel

For Redis Cluster or Sentinel configurations, use the standard Spring Data Redis cluster or sentinel properties:

application.yml

spring:
  data:
    redis:
      cluster:
        nodes:
          - redis-node-1:6379
          - redis-node-2:6379
          - redis-node-3:6379

Run Redis locally with Docker

For local development, you can quickly start a Redis instance using Docker:

Terminal

docker run --name redis-ratelimiter -p 6379:6379 -d redis:7-alpine

This command starts Redis 7 in Alpine Linux, exposing it on port 6379.

For production environments, consider using managed Redis services like AWS ElastiCache, Azure Cache for Redis, or Google Cloud Memorystore.

Optional configuration

The starter provides several configuration properties to customize behavior. All properties are optional and have sensible defaults:

application.yml

ratelimiter:
  enabled: true
  redis-key-prefix: ratelimiter
  fail-open: false
  include-http-headers: true
  metrics-enabled: true

Configuration properties reference

Property	Type	Default	Description
ratelimiter.enabled	boolean	true	Master switch to enable or disable the rate limiter auto-configuration
ratelimiter.redis-key-prefix	string	ratelimiter	Prefix used for all Redis bucket keys
ratelimiter.fail-open	boolean	false	When true, allows requests if Redis is unavailable (fail-open). When false, rejects requests if Redis is unavailable (fail-closed)
ratelimiter.include-http-headers	boolean	true	When true, includes Retry-After and RateLimit-* headers in HTTP 429 responses
ratelimiter.metrics-enabled	boolean	true	When true, records Micrometer metrics for rate limiter operations

Setting fail-open=true means requests will be allowed when Redis is unavailable. This can be useful for resilience but removes rate limiting protection during Redis outages. Use with caution in production.

Verify installation

After adding the dependency and configuring Redis, start your Spring Boot application. You should see log messages indicating the rate limiter auto-configuration has activated:

Console output

INFO  RateLimiterAutoConfiguration - Rate limiter starter auto-configuration enabled

1. Check Redis connectivity

   Ensure your application can connect to Redis. Check the logs for any connection errors.

2. Add a test annotation

   Add @RateLimit to a test controller or service method to verify the starter is working.

3. Test the rate limit

   Make multiple requests to the annotated endpoint and verify you receive HTTP 429 responses when the limit is exceeded.

Dependency tree

The starter includes these main dependencies:

• spring-boot-autoconfigure - Auto-configuration support
• spring-context - Spring IoC container
• spring-aop - AOP interceptor support
• spring-web - HTTP exception handling
• spring-data-redis - Redis operations
• lettuce-core - Redis client
• micrometer-core - Metrics recording

All dependencies are included automatically when you add the starter. You don’t need to add them individually.

What’s next

Quick start

Follow the step-by-step guide to implement rate limiting in your application

Back to introduction

Return to the introduction page