Skip to main content

​
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: 
<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: 
spring:
  data:
    redis:
      host: localhost
      port: 6379

​
Redis with authentication

If your Redis instance requires authentication: 
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: 
ratelimiter:
  enabled: true
  redis-key-prefix: ratelimiter
  fail-open: false
  include-http-headers: true
  metrics-enabled: true

​
Configuration properties reference

PropertyTypeDefaultDescription
ratelimiter.enabledbooleantrueMaster switch to enable or disable the rate limiter auto-configuration
ratelimiter.redis-key-prefixstringratelimiterPrefix used for all Redis bucket keys
ratelimiter.fail-openbooleanfalseWhen true, allows requests if Redis is unavailable (fail-open). When false, rejects requests if Redis is unavailable (fail-closed)
ratelimiter.include-http-headersbooleantrueWhen true, includes Retry-After and RateLimit-* headers in HTTP 429 responses
ratelimiter.metrics-enabledbooleantrueWhen 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

Build docs developers (and LLMs) love

Get started for freeTalk to us