A local environment for Valkey with Docker Compose

All rights reserved — https://valkey.io/

Introduction

I have created a small project on GitHub that provides a docker compose file and a basic directory structure to have a local development environment with a Valkey database.

TL;DR

If you want to skip the details and just use a docker compose file to run a Valkey instance, here you go :

• Get the project on GitHub (you can get the zip file, clone or fork the GitHub repository)
• Go to the docker-compose-examples/valkey-docker-compose-examples/valkey-single directory and run the following command : docker compose -f dc-valkey-single.yml up -d to run Valkey.
• Go to the docker-compose-examples/valkey-docker-compose-examples/valkey-bundle directory and run the following command : docker compose -f dc-valkey-bundle.yml up -d to run a version of Valkey which contains additional modules.
• Access the instance with the Valkey CLI by opening an interactive shell on the running container of the Valkey instance with docker exec -it valkey /bin/sh and then in the open shell run the CLI with valkey-cli. You can even run directly docker exec -it valkey valkey-cli if you do not really need to use the shell on the running container.
• You also have an instance of Redis Insight available on localhost:8001.
• To stop the containers you can respectively type : docker compose -f dc-valkey-single.yml down or docker compose -f dc-valkey-bundle.yml down.

The docker compose files

First, you have to fetch the project on GitHub. You should find in the project a valkey-docker-compose-examples directory that contains the following sub-directories and files :

The various directories and files available in the GitHub project

The following picture shows the docker compose file dc-valkey-single.yml and its relations to the other files. The version of the docker compose file docker-compose-examples/valkey-docker-compose-examples/valkey-bundle is very similar.

Content of the docker compose file dc-valkey-single.yml

The docker compose file by itself is moderately long and quite straightforward.

One service is defined for the valkey instance. The retrieved container image is the latest. You can (and in some case you should) change to point to a specific version of valkey.

Valkey is originally an open source fork of Redis and as such it can be accessed with tool as Redis Insight. Thus, in the file there is one other service for Redis Insight. The retrieved image is also the latest but that can be adapted easily to get a specific version. The examples on the project on GitHub are a little bit more detailled on this point.

The .env file defines some system variables used in the docker compose file for Redis Insight. You can of course change the values to your needs if necessary. The detailled of the different settings for Redis Insight is available here. In the project presented here, Redis Insight is pre-configured with the environment variables to have the dockerised local Valkey instance directly accessible.

A network and several volumes are defined. It is not strictly necessary but it is a good practice.

Configuration

The file originated from here but has been modified.

There are only two modifications in the provided valkey.conf :

• The line bind 127.0.0.1 -::1 has been commented and is now #bind 127.0.0.1 -::1
• The protected mode is disabled protected-mode no

This is to allow the connection from the host machine into the Valkey instance in the container. As a matter of fact we throw the security to the wind. This is ok only because in our case it is a local use for development purpose here.

Extract from https://raw.githubusercontent.com/valkey-io/valkey/9.0/valkey.conf

Running and stopping the containers

Valkey

To run the containers and the associated Valkey instance with docker compose, open a shell, go to the valkey-docker-compose-examples/valkey-single directory and run the following command :

docker compose -f dc-valkey-single.yml up -d

If you are on Windows, you can use WSL or if you have the docker engine installed (via Docker Desktop or Rancher Desktop) you can use Windows Powershell.

Running docker compose with dc-valkey-single.yml

The running containers (Valkey and Redis Insight) in Rancher Desktop

To stop the container, type the following in the shell, from the directory which contains your docker compose file dc-valkey-single.yml:

docker compose -f dc-valkey-single.yml down

Stopping the containers

Valkey Bundle

To run the container associated with the Valkey instance with docker compose, open a shell, go to the valkey-docker-compose-examples/valkey-bundle directory and run the following command :

docker compose -f dc-valkey-bundle.yml up -d

Running docker compose with dc-valkey-bundle.yml

The running containers (Valkey and Redis Insight) in Rancher Desktop

To stop the container, type the following in the shell, from the directory which contains the valkey-bundle.yml docker compose file:

docker compose -f dc-valkey-bundle.yml down

Stopping the containers

Accessing Valkey with the CLI in the container

In a shell, run the following command line :

docker exec -it valkey /bin/sh

You are now in a shell in the container.

Then type valkey-cli.

If you do not really need to use the shell on the running container, you can run directly docker exec -it valkey valkey-cli .

Either way, you can now type Valkey command. For example KEYS * which output the list of keys with any name in the database. In this empty database, there should be none. Or maybe you can try INFO modules which lists the modules available with your instance.

You can type quit to exit redis-cli and of course exit to exit the shell if need be.

Opening the Valkey CLI in the Redis Container

Accessing Valkey from the Redis Insight Web Interface

Redis Insight is available as a Web Application and as a Desktop client.

In this paragraph we demonstrate the use of the Web Application deployed as a container along side the Valkey instance itself.

You have to connect to the url http://localhost:8001 with your favorite browser.

On your first connexion you are welcomed with some questions about the privacy settings.

Privacy settings on first connection to Redis Insight

Suggested settings for Redis Insight

After answering them, you access the tool in itself.

Initial screen of Redis Insight

As you can see on the previous screenshot, the instance is pre-configured with a Valkey database on valkey:6379.

You can see that the hostname, is valkey, this is the host defined in Docker Compose : the instance of Redis Insight is on the same network in docker as Valkey, and can access it directly with its defined hostname. Furthermore, it is the configured Redis Host with the environment variable RI_REDIS_HOST in the .env file.

If you wish, you can edit the alias of the database.

Accesssing the menu to edit the database

Editing the database

You can now click on the local database (with alias valkey:6379 on the screenshot — the alias has not been changed in the previous step) to access this base.

Accessing the database on localhost

The base is empty so there is not much to display.

You land on the Browser page but with the button on the left you can now access the Workbench or the Analysis Tool for example.

Accessing the workbench

You can also install the desktop client which is an Electron application and works in a similar way.

The only attention point is for the Valkey instance host : it should be 127.0.0.1 or localhost, and not valkey as you access the instance from outside docker.

Redis Insight offers to load sample data in Redis, but it also works with Valkey.

Loading sample data

Loaded sample data — Tetris leaderboard example

If you want to experiment with Valkey but do not readily have available data it is a good way to start.

Accessing the Redis instance with Another Redis Desktop Manager

There is at least another alternative for a desktop client : Another Redis Desktop Manager.

You can download the binary from GitHub.

The installation is quite straightforward and you can only get a zip archive.

When you run the executable for the first time, a window similar to the following screenshot should open.

First connection to Another Redis Desktop Manager

When you click on the button New Connection on the left-side top corner, a new window should open. In this new window you can enter the settings for a new connection.

To connect to the dockerised local instance, you will note that the host should be 127.0.0.1 or localhost, as you access the instance from outside docker so to speak. As such the host is not valkey as it was for the dockerised Redis Insight.

Creating a new Connection in Another Redis Desktop Manager

After clicking on the OK button, the new connection is now available. When selecting it, you can now access the Valkey instance.

Accessing the local Valkey instance in Another Redis Desktop Manager

Conclusion

With all this, you should have the basis for a local development environment for **Valkey, that you can use “as is” or customize if needed. Some tools to access your data in [Valkey](https://valkey.io/) have also been presented. You should have all that is necessary to start with [Valkey](https://valkey.io/)**.

Complementary resources

• Valkey : official site andGitHub.
• Valkey Bundle — GitHub
• DockerHub : Valkey and Valkey Bundle
• Official Redis Insight Docker Image
• Another Redis Desktop Manager : official site, GitHub and Releases

I have also written similar articles on Redis, MongoDB, PostgreSQL and Dependency Track if you’re interested.

I thank my colleague Thomas Verhoken for his proofreading.