[RFC]: Docker Support for Valkey Admin

[robmarlow]

[RFC] Docker Support for Valkey Admin

Summary

This RFC proposes adding Docker support to Valkey Admin, enabling deployment as a containerized web application. The primary use case is running Valkey Admin in Kubernetes clusters to connect to in-cluster Valkey nodes, replacing Redis Insights as the cluster management interface.

Motivation

We need to deploy Valkey Admin in our Kubernetes environment to connect to in-cluster Valkey nodes. This will replace our current Redis Insights deployment, providing a modern web-based interface for managing Valkey clusters directly from within the cluster.

Design Proposal

Architecture

The Docker implementation will provide the web-based subset of Valkey Admin features (as mentioned in the README, some features like hotkeys and commandlogs require Electron). The container will run:

1. WebSocket Server (port 8080): The backend server that handles Valkey connections
2. Frontend Server (port 5173): Static file server for the React frontend

Technical Approach

Multi-Stage Docker Build

The Dockerfile will use a multi-stage build pattern for optimal image size and build efficiency:

Stage 1: Builder

• Base: node:22-bookworm-slim
• Copies package files first (for better layer caching)
• Installs all dependencies via npm ci
• Copies source code
• Builds all components using npm run build:all

Stage 2: Production

• Base: node:22-bookworm-slim (minimal runtime)
• Installs serve globally for static file serving
• Copies only built artifacts from builder stage:
  • apps/server/dist (server bundle)
  • apps/frontend/dist (frontend build)
  • apps/metrics/dist (metrics build)
  • apps/metrics/config.yml (metrics config)
• Copies only necessary runtime dependencies:
  • @valkey/* (Valkey client libraries)
  • ws (WebSocket library)
  • long, protobufjs, @protobufjs (protobuf dependencies)
  • p-limit, ramda (utility dependencies)

Entrypoint Script

A shell script (docker-entrypoint.sh) will:

• Start the WebSocket server in the background
• Start the frontend static file server in the background
• Handle graceful shutdown via signal trapping (TERM, INT)
• Wait for both processes and clean up on exit

Docker Best Practices

• .dockerignore file to exclude unnecessary files from build context
• Optimized layer caching (package files copied before source)
• Minimal production image (only runtime dependencies)
• Proper signal handling for graceful container shutdown
• Non-root user consideration (can be added in future if needed)

Files to Add

1. Dockerfile: Multi-stage build configuration
2. docker-entrypoint.sh: Startup and signal handling script
3. .dockerignore: Exclude patterns for build context optimization
4. README.docker.md (optional): Docker-specific documentation

Usage Example

# Build the image
docker build -t valkey-admin .

# Run the container
docker run -d \
  --name valkey-admin \
  -p 8080:8080 \
  -p 5173:5173 \
  valkey-admin

# Access the web interface
open http://localhost:5173

Kubernetes Deployment

The containerized version is designed to run in Kubernetes, connecting to in-cluster Valkey nodes via their service endpoints. This enables cluster operators to manage Valkey instances without requiring desktop application access.

Ports

• 8080: WebSocket server (backend)
• 5173: Frontend web server

Limitations

As noted in the README, the web version provides a subset of features. The following Electron-specific features will not be available:

• Hotkeys
• Commandlogs
• Full desktop integration

This is expected and documented behavior.

Impact

Positive

• ✅ Enables Kubernetes deployment for in-cluster Valkey management
• ✅ Replaces Redis Insights with a modern Valkey-native interface
• ✅ No breaking changes to existing functionality

Considerations

• ⚠️ Web version has limited features (already documented - no hotkeys/commandlogs)
• ⚠️ Additional maintenance for Docker-related files
• ⚠️ Need to keep Dockerfile in sync with build process changes

Implementation Plan

1. Create Dockerfile with multi-stage build
2. Create docker-entrypoint.sh for process management
3. Create .dockerignore for build optimization
4. Test build and runtime behavior
5. Update documentation (if needed)

Questions for Review

1. Should we add health check endpoints for Kubernetes liveness/readiness probes?
2. Should we support environment variables for configuration (e.g., default connection endpoints)?

[arseny-kostenko]

Hi @robmarlow, thanks for submitting an issue/RFC.

To enable k8s deployment, I don't think we need to expose the backend for frontend server's port — as it's within the same container together with the UI and doesn't have a public interface. Also, the metrics service in k8s deployment should be a sidecar deployment with a valkey node, i.e. one valkey node + one metrics service within one valkey pod.

We're also planning to make the backend for frontend server entirely a proxy, so all metrics collection happens in the metrics service.

[KIvanow]

@robmarlow Curious about your use case — is this primarily for cluster management (key browsing, commands) or monitoring/observability? I'm working on a Valkey observability tool and trying to understand what gaps people are hitting with existing tooling.

[robmarlow]

@KIvanow yes this is for cluster management inside of a k8s cluster. we currently deploy Redis insights (https://redis.io/insight/) and expose it via an internal load balancer. We have dev teams that log on to look at keys primarily.

I made a Docker container for this from this repo/project and I was really just wanting to contribute it back to whomever may also want it as a dockerfile.

[KIvanow]

@KIvanow yes this is for cluster management inside of a k8s cluster. we currently deploy Redis insights (https://redis.io/insight/) and expose it via an internal load balancer. We have dev teams that log on to look at keys primarily.

I made a Docker container for this from this repo/project and I was really just wanting to contribute it back to whomever may also want it as a dockerfile.

Got, thank you for the detailed explanation!

[robmarlow]

@KIvanow am I good to open a PR with a dockerfile, .dockerignore, entrypoint script and edit a section of the README?

[arseny-kostenko]

@robmarlow, before opening a PR, please address my comment above

[jakob-keller]

Container support would indeed be great! We have a similar, AWS-centric use case, currently served by RedisInsight. A drop-in replacement would need to (eventually) fulfill these requirements:

• container images published to Docker Hub or ECR Public
• runs on ECS Fargate, ideally on Graviton (arm64) hardware
• works behind ALB (load balancer for TLS termination and authentication), e.g. provides a health check URL
• compatible with ElastiCache for Valkey clusters (cluster mode on and off)
• support IPv6-only subnets
• supports injection of relevant database configuration through environment variables

[arseny-kostenko]

@jakob-keller, thanks for the requirements. This is issue is in scope for a GA release that's in a month or two away.