Redis Local Setup & Troubleshooting Guide

Windows Docker Desktop + Linux Docker + Native Redis

1. What is Redis?

Redis is an in-memory data store commonly used for:

By default, Redis listens on:

Host: localhost
Port: 6379

2. Redis Local Architecture

Spring Boot Application
          |
          | localhost:6379
          v
+----------------------+
|       Redis          |
|                      |
|      Port 6379       |
+----------------------+

Docker option:

Spring Boot
     |
     | localhost:6379
     v
Docker
     |
     v
local-redis container
     |
     v
Redis 7

3. Redis on Windows Using Docker Desktop

Recommended approach for local Windows development: Run Redis inside Docker Desktop instead of installing Redis natively.

Step 1 — Install Docker Desktop

Download and install Docker Desktop for Windows.

After installation, restart Windows if requested.

Start Docker Desktop and wait until the Docker Engine is running.

Step 2 — Verify Docker

Open PowerShell or Command Prompt.

docker version

You should see both Client and Server information.

docker info
If you receive an error such as dockerDesktopLinuxEngine not running, start Docker Desktop first.

Step 3 — Download Redis Image

docker pull redis:7

This downloads Redis version 7 from Docker Hub.

Step 4 — Create and Start Redis Container

docker run -d --name local-redis -p 6379:6379 redis:7

Explanation:

Option Meaning
docker run Create and start a new container
-d Run in detached/background mode
--name local-redis Container name
-p 6379:6379 Map Windows host port 6379 to Redis container port 6379
redis:7 Redis version 7 image

Step 5 — Verify Container

docker ps

Expected output should contain something similar to:

CONTAINER ID   IMAGE     STATUS       PORTS
xxxxxxx        redis:7   Up ...       0.0.0.0:6379->6379/tcp

The important part is:

redis:7
Up
0.0.0.0:6379->6379/tcp

Step 6 — Test Redis

docker exec -it local-redis redis-cli ping

Expected:

PONG
If you see PONG, Redis is working correctly.

4. Important: docker run vs docker start

This is one of the most common Docker Redis mistakes.

Command Purpose
docker run Create a new container and start it
docker start Start an existing stopped container
docker stop Stop a running container
docker restart Restart an existing container
docker rm Remove a container

If local-redis already exists

Do NOT execute docker run again.

docker start local-redis

Expected:

local-redis

Verify

docker ps

Test

docker exec -it local-redis redis-cli ping

Expected:

PONG

5. Windows Redis Troubleshooting

Problem 1 — Container exists but is stopped

Check all containers:

docker ps -a

If you see:

local-redis   redis:7   Exited

Start it:

docker start local-redis

Problem 2 — docker start local-redis fails

First check:

docker ps -a

Then check Redis logs:

docker logs local-redis

The logs normally reveal configuration, startup, permission, or port-related problems.

Problem 3 — Container name already exists

You may see:

Conflict. The container name "/local-redis"
is already in use

This means the container already exists.

Do not execute docker run again.

docker start local-redis

Problem 4 — Port 6379 is already allocated

You may see:

Bind for 0.0.0.0:6379 failed:
port is already allocated

Check Windows port usage:

netstat -ano | findstr :6379

If another application is using 6379, you can either stop that application or map Redis to another host port.

docker run -d --name local-redis -p 6380:6379 redis:7

In this case Redis is accessed from the Windows host using:

localhost:6380

Problem 5 — Docker Engine is not running

If you see an error mentioning:

dockerDesktopLinuxEngine

Start Docker Desktop and wait for the Docker Engine to become ready.

Then test:

docker info

Problem 6 — Test Redis from Windows without redis-cli

You can test whether port 6379 is reachable using PowerShell:

Test-NetConnection localhost -Port 6379

Expected:

TcpTestSucceeded : True

6. Start Redis Automatically After Docker Restart

To automatically restart Redis when Docker restarts:

docker update --restart unless-stopped local-redis

Verify:

docker inspect local-redis

This is useful for local development because you don't have to manually start Redis every time Docker Desktop restarts.

7. Redis on Linux Using Docker

Step 1 — Verify Docker

docker --version
docker info

Step 2 — Pull Redis

docker pull redis:7

Step 3 — Run Redis

docker run -d --name local-redis -p 6379:6379 redis:7

Step 4 — Verify Container

docker ps

Step 5 — Test Redis

docker exec -it local-redis redis-cli ping

Expected:

PONG

Step 6 — Restart Existing Container

docker start local-redis

or:

docker restart local-redis

8. Native Redis Installation on Linux

If Docker is not required, Redis can be installed directly on a Linux machine.

Step 1 — Update packages

sudo apt update

Step 2 — Install Redis

sudo apt install redis-server -y

Step 3 — Enable Redis at system startup

sudo systemctl enable redis-server

Step 4 — Start Redis

sudo systemctl start redis-server

Step 5 — Check Redis status

sudo systemctl status redis-server

You should see that the service is active/running.

Step 6 — Test Redis

redis-cli ping

Expected:

PONG
PONG means the Redis server is running and accepting connections.

9. Linux Native Redis Troubleshooting

Check Redis status

sudo systemctl status redis-server

Start Redis

sudo systemctl start redis-server

Restart Redis

sudo systemctl restart redis-server

Stop Redis

sudo systemctl stop redis-server

Enable Redis at boot

sudo systemctl enable redis-server

Check port 6379

sudo ss -lntp | grep 6379

Another useful command:

sudo lsof -i :6379

Check Redis logs

sudo journalctl -u redis-server

10. Linux Docker Troubleshooting

Check running containers

docker ps

Check all containers

docker ps -a

Check Redis logs

docker logs local-redis

Start stopped Redis

docker start local-redis

Restart Redis

docker restart local-redis

Test Redis

docker exec -it local-redis redis-cli ping

11. Useful Redis CLI Commands

Connect to Redis:

redis-cli

Test connection:

redis-cli ping

Check Redis information:

redis-cli info

Check server information:

redis-cli info server

Check memory:

redis-cli info memory

Check keys:

redis-cli keys "*"
Avoid using KEYS * on large production Redis databases because it can be expensive. It is fine for simple local testing.

12. Spring Boot Redis Configuration

Once Redis is running locally on port 6379, configure your Spring Boot application accordingly.

Spring Boot 2.x

spring.redis.host=localhost
spring.redis.port=6379

Spring Boot 3.x

spring.data.redis.host=localhost
spring.data.redis.port=6379
If your application uses Spring Boot 2.7.x, use the spring.redis.* properties.

13. Complete Redis Connection Verification

Use the following sequence whenever your Spring Boot application reports:

RedisConnectionFailureException:
Unable to connect to Redis

Step 1 — Check Docker

docker info

Step 2 — Check Redis container

docker ps

Step 3 — If container is stopped

docker start local-redis

Step 4 — Check all containers

docker ps -a

Step 5 — Check logs if Redis doesn't start

docker logs local-redis

Step 6 — Test Redis directly

docker exec -it local-redis redis-cli ping

Expected

PONG

Step 7 — Windows port test

Test-NetConnection localhost -Port 6379

Step 8 — Restart Spring Boot

After Redis returns PONG and port 6379 is reachable, restart the Spring Boot application.

14. Common Errors and Solutions

Error Likely Cause Solution
Unable to connect to localhost:6379 Redis is not running Start Redis container/service
dockerDesktopLinuxEngine Docker Desktop/Engine is not running Start Docker Desktop
container name already in use Container already exists Use docker start local-redis
container is not running Redis container is stopped Use docker start local-redis
port is already allocated Another process uses 6379 Find/stop process or use another host port
redis-cli not found Redis CLI not installed locally Use docker exec or install Redis CLI
Connection refused Redis is not listening on expected port Check service/container and port

15. Docker Redis Cleanup

If you want to completely remove the existing local Redis container:

docker stop local-redis
docker rm local-redis

Then create it again:

docker run -d \
  --name local-redis \
  -p 6379:6379 \
  redis:7

On Windows PowerShell, you can use the single-line version:

docker run -d --name local-redis -p 6379:6379 redis:7

16. Recommended Commands to Remember

Purpose Command
Check Docker docker info
Running containers docker ps
All containers docker ps -a
Start Redis docker start local-redis
Stop Redis docker stop local-redis
Restart Redis docker restart local-redis
Redis logs docker logs local-redis
Redis ping docker exec -it local-redis redis-cli ping
Expected response PONG

17. Final Redis Checklist

Before starting Spring Boot, verify:

  • Docker Desktop is running on Windows
  • Docker Engine is running
  • Redis image exists
  • Redis container exists
  • Redis container status is UP
  • Port 6379 is mapped
  • docker exec -it local-redis redis-cli ping returns PONG
  • Spring Boot points to localhost:6379

Golden Rule

docker ps
        |
        | Is local-redis running?
        |
        +-- YES --> docker exec -it local-redis redis-cli ping
        |                    |
        |                    +-- PONG --> Redis is READY
        |
        +-- NO --> docker ps -a
                       |
                       +-- local-redis exists
                       |       |
                       |       +--> docker start local-redis
                       |
                       +-- local-redis does not exist
                               |
                               +--> docker run -d
                                    --name local-redis
                                    -p 6379:6379
                                    redis:7

18. Windows Quick Reference

docker info

docker ps

docker ps -a

docker start local-redis

docker exec -it local-redis redis-cli ping

docker logs local-redis

Test-NetConnection localhost -Port 6379
Final expected Redis result: PONG

19. Linux Quick Reference

Docker Redis

docker info
docker ps
docker ps -a
docker start local-redis
docker exec -it local-redis redis-cli ping
docker logs local-redis

Native Redis

sudo systemctl status redis-server
sudo systemctl start redis-server
sudo systemctl restart redis-server
sudo systemctl enable redis-server
redis-cli ping
Final expected Redis result: PONG

20. Summary

For Windows local development, Docker Desktop with Redis 7 is generally the simplest approach.

For Linux, Redis can either be run through Docker or installed directly using the Linux package manager.

The most important troubleshooting sequence is:

docker ps
docker ps -a
docker start local-redis
docker logs local-redis
docker exec -it local-redis redis-cli ping

If the final command returns:

PONG

Redis itself is ready. Any remaining RedisConnectionFailureException in Spring Boot should then be investigated from the application's Redis host/port/password configuration or network environment.