Redis Insight Configurator

A .NET Console application that can configure parts of a Redis Insight instance via its REST API.
This app is designed to run as a "sidecar" Docker container alongside the target Redis Insight.

Inspired by:

• GitHub, .NET Aspire - PR: Change Redis Insight to use environment variables for preconfigured database connections

Warning

Redis Insight exposes a REST API that can be used for programmatic interaction only when it is running in Docker.

Tip

Redis Insight introduced a way to preconfigure database connections using environment variables or a JSON file since version v2.68.
If you only need to preconfigure connections - see the official documentation - but be sure to read the pros/cons comparison below. 😉

How does it work?

The application is packaged in a Docker container. When it starts, it:

• parses environment variables prefixed with RIC_ (Redis Insight Configurator)
• waits for the target Redis Insight API to become available and healthy
• if the target is not yet configured (first run), sets configuration values and accepts user agreements, so the UI works without interruptions
• synchronizes Redis connections of Redis Insight according to the provided "connections string" - that is, it can add new connections and delete ones that are no longer needed (note the "s" - you can specify multiple connections 😉)
• exits, returning an exit code that reflects the result

How to run

To try the example: clone the repository and run the provided Docker Compose stack:

docker compose up
# to clean up run
# docker compose down -v

This will automatically pull Redis and Redis Insight images, build the application, and start the example stack for you.

Redis Insight web UI will be available at http://localhost:5540, and Swagger API docs at http://localhost:5540/api/docs.
You should see two preconfigured Redis connections in the UI.

Tip

You can speed up startup of the provided compose.yaml by commenting out all dependencies (the "depends_on" sections).

Then you can adjust the behavior of the configurator application by setting environment variables - see the "Environment variables" section below to adapt it to your Compose stacks or use cases.

Environment variables

Here is a list of environment variables you can use to alter the application's behavior:

• RIC_API_ENDPOINT (string, mandatory) - HTTP address of the Redis Insight instance. Example: http://localhost:5540
• RIC_API_PATH (string, default: api) - HTTP path to the Redis Insight API
• RIC_API_TIMEOUT (int, default: 30) - timeout for Redis Insight API health check in seconds
  • Note: The application will use periodic polling every 5 seconds, with a 1-second interval in between attempts. So RIC_API_TIMEOUT defines the maximum time the application may spend trying to get a successfull response.
• RIC_SETTINGS_UI_THEME (string, default: DARK) - UI theme for Redis Insight (allowed values: "LIGHT", "DARK", "SYSTEM")
• RIC_SETTINGS_DATE_FORMAT (string, default: yyyy.MM.dd HH:mm:ss:.sss) - date and time format shown in the UI
• RIC_SETTINGS_TIMEZONE (string, default: local) - timezone used by the UI (allowed values: local, UTC)
• RIC_SETTINGS_SCAN_THRESHOLD (int, default: 10000) - maximum number of Redis keys to scan (must be at least 500)
• RIC_SETTINGS_BATCH_SIZE (int, default: 5) - batch size for Redis commands
• RIC_CONNECTIONS_STRING (string, mandatory) - a string defining Redis connection(s) to configure
  • Example: redis-cache1:6379|default|test-pass1|Test1; redis-cache2||test-pass2|Test2
  • Format:

  <host1>:<port1>|<username1>|<password1>|<alias1>;
  <host2>:<port2>|<username2>|<password2>|<alias2>;
  ...
  

  • Explanation:
    • : separates host and port.
    • | separates parameters of a single connection (host:port, username, password, alias).
    • Only host is mandatory. Other fields are optional; default values will be used when omitted: port = 6379, username = default, password = empty string, alias = <host>:<port>.
    • Note: there is currently no way to escape the | character, so usernames, passwords, or aliases containing | are not supported.
• RIC_DONT_CREATE_CONNECTIONS - if defined (any value), new connections will not be added during synchronization (i.e. sync becomes "delete only")
• RIC_DONT_DELETE_CONNECTIONS - if defined (any value), existing connections will not be deleted during synchronization (i.e. sync becomes "append only")

Exit codes

List of possible exit codes of the applicaiton:

• 0 - success: all done.
• 1 - the application was terminated by Ctrl+C.
• 2 - warning: there were some non-critical errors. The application finished, but some connections may not be configured as expected.
• 3 - critical error: the application terminated prematurely due to an unrecoverable error. Check logs and fix the configuration.

Warning

Remember that Docker Compose always return exit code 0!
You need a special approach to retrieve the actual exit code of the application container (which is out of scope of this project).

This App vs Built-in Redis Insight configuration possibilities

Redis Insight supports pre-configuring database connections - either via environment variables or a JSON file - starting with version v2.68 (see the docs).

But this app adds value beyond the built-in capabilities:

• It allows setting additional settings, like UI theme, date and time format, timezone, and so on.
• This app waits for the Redis Insight instance to start and validates each connection before adding it. If a target Redis server is not yet available when the configurator runs, the connection will be skipped (rather than added and left broken).
• It is safe to run this app multiple times to re-synchronize connections - it will not break existing ones, unless you explicitly misconfigure it to do so (via "cut only" or "append only" mode).

Usage tips

Normal operation:

• The application is supposed to exit as soon as it finishes - do not apply Docker restart policies such as restart: unless-stopped.
• It is safe to run this application multiple times - it will not attempt to re-create connections that already exist and are still listed in the connections string.
• Redis Insight settings will be applied only once, and only on a "clean" instance (i.e. when no user agreements have been accepted yet). If you have already manually closed the welcome screen pop‑up, the application will skip applying settings parameters.
• You can configure the application via an appsettings.json file (by bind‑mounting it into the /app folder) instead of using environment variables - but this is more of a configuration-system side effect than a feature.
  • The file example is in the code.

Troubleshooting:

• To debug connectivity issues, you may:
  • set RIC_Logging__LogLevel__Default environment variable to "Debug",
  • or set RIC_Logging__LogLevel__System.Net.Http.HttpClient to "Information" for even more detailed network-communication output.

Useful information

Competitor projects:

• Github, Deepmancer, RedisInsight Docker Automated Configuration

Links:

• Redis, Docs, Preconfigure database connections

Project status

This is a weekend project born from a fleeting idea I had while experimenting with Redis Insight and reviewing its docs.
The project has a “Portfolio” status - no feature‑PRs are expected.
If you have ideas, feel free to open a discussion in the issues.

Possible improvements

List of things "nice to have":

• Optimize Docker image size (investigate .NET AOT, but remember of its limitations regarding JSON serialization, verify if StringOrStringArrayConverter will still work afterward) - expected image size is ~10Mb
  • Partial optimization was done by switching to Alpine base image (which resulted in size decrease from ~250Mb to ~98Mb)
• Mitigate the limitation of not being able to escape the "|" character in the connections string
• Publish the Docker image to Docker Hub

Software Bill of Materials

Core:

• .NET 10
• Redis
• Redis Insight

Tools:

• Docker
• Git / GitHub
• JetBrains Rider

Thank you to all the creators and maintainers of these building blocks!

Bonus

Q: How do I configure a Redis Insight instance via its REST API manually?
A: Use the following PowerShell + curl example commands.

First, set user agreements (without this you won’t be able to configure connections):

$settingsBody = '{
  "theme": "DARK",
  "timezone": "local",
  "dateFormat": "yyyy.MM.dd HH:mm:ss:.sss",	
  "agreements": {
    "eula": false,
    "analytics": false,
    "notifications": false,
    "encryption": false
  }
}'

curl -X PATCH "http://localhost:5540/api/settings" `
     -H "Content-Type: application/json" `
     -d "$settingsBody" >$null 2>&1

Then add Redis connections:

$connectionBody1 = '{
  "host": "localhost",
  "port": 6379,
  "password": "in-memory-cache-pass",
  "name": "In-memory Cache #1"
}'

curl -X POST "http://localhost:5540/api/databases" `
     -H "Content-Type: application/json" `
     -d "$connectionBody1" >$null 2>&1

$connectionBody2 = '{
  "host": "localhost",
  "port": 6380,
  "password": "in-memory-cache-pass",
  "name": "In-memory Cache #2"
}'

curl -X POST "http://localhost:5540/api/databases" `
     -H "Content-Type: application/json" `
     -d "$connectionBody2" >$null 2>&1