Setting Up Valkey or Redis on River Containers
Learn how to deploy a Valkey or Redis caching layer directly from an external registry on River Containers
Adding an in-memory datastore like Valkey or Redis to your application drastically improves response times, simplifies session management, and powers background job queues.
With River Containers, you don't need to write a custom Dockerfile or push an image to a private registry just to get a caching layer running. Because River Containers places all of your containers on the same isolated network by default, you can pull an official Valkey or Redis image directly from an external registry and connect to it.
Prerequisites
- An active River account.
- An existing application container deployed on River Containers (or one ready to deploy) that will connect to your cache.
Step 1: Create the Valkey or Redis Container
Instead of building and pushing a custom image, you can instruct River to pull the official pre-built image directly from Docker Hub.
- Log in to your River dashboard and click New Container (or Create Container).
- In the External Registry Image field, enter the official image tag for your preferred datastore:
# For Valkey (Recommended - Lightweight Alpine image)
valkey/valkey:8-alpine
# For Valkey (Standard)
valkey/valkey:latest
# For Redis (Lightweight Alpine image)
redis:7-alpine- Configure the Port: Set the container port to
6379(the default port for both Valkey and Redis). You do not need to expose this port publicly since your application will communicate with it over the internal network. - Click Deploy: Wait a few seconds for River Containers to pull the image and transition the container status to Running.
Step 2: Grab Your Container ID
Once the container is running, River Containers automatically attaches it to your default private network and registers its Container ID with the internal DNS server.
- Open your newly created Valkey/Redis container in the River Containers dashboard.
- Locate the Container ID (a 12-character alphanumeric string, such as
e4f8a9b2c1d3). - Copy this ID—it serves as the internal hostname your application will use to reach the datastore.
Step 3: Configure Your Application Environment
Inside your main application container on River Containers, configure your Redis/Valkey client using the Container ID as the host and 6379 as the port.
Add the REDIS_URL environment variable to your application container's settings:
# Format: redis://<container-id>:6379
REDIS_URL=redis://e4f8a9b2c1d3:6379
# If you passed a custom --requirepass argument to secure the instance:
REDIS_URL=redis://default:your_strong_password@e4f8a9b2c1d3:6379Step 4: Connect from Your Code
Use your standard Redis client library to connect to the cache via the REDIS_URL environment variable.
TypeScript / Node.js (ioredis)
import Redis from 'ioredis';
// Connects to redis://e4f8a9b2c1d3:6379 from environment variables
const cache = new Redis(process.env.REDIS_URL!);
export async function verifyCacheConnection() {
await cache.set('healthcheck', 'Connected to Valkey via River Containers!', 'EX', 60);
const status = await cache.get('healthcheck');
console.log('Cache status:', status);
}Python (redis-py)
import os
import redis
# Connect using the Container ID hostname
redis_url = os.getenv("REDIS_URL", "redis://e4f8a9b2c1d3:6379")
client = redis.from_url(redis_url, decode_responses=True)
client.set("healthcheck", "Connected to Valkey via River Containers!", ex=60)
print("Cache status:", client.get("healthcheck"))Go (go-redis)
package main
import (
"context"
"fmt"
"os"
"[github.com/redis/go-redis/v9](https://github.com/redis/go-redis/v9)"
)
func main() {
ctx := context.Background()
opt, err := redis.ParseURL(os.Getenv("REDIS_URL"))
if err != nil {
panic(err)
}
rdb := redis.NewClient(opt)
err = rdb.Set(ctx, "healthcheck", "Connected to Valkey via River Containers!", 0).Err()
if err != nil {
panic(err)
}
val, _ := rdb.Get(ctx, "healthcheck").Result()
fmt.Println("Cache status:", val)
}Production Tips
- Never Hardcode the Container ID: Container IDs are ephemeral—if you delete and recreate your Valkey or Redis container, it will receive a brand new ID. Always inject the ID via environment variables (
REDIS_URL) on your app container so you can update it without redeploying your code. - Prefer
-alpineVariants: Images likevalkey/valkey:8-alpineweigh under 20 MB compared to 45+ MB for standard images, resulting in faster pulls and near-instant cold starts on River Containers. - Set a Key Eviction Policy: When using Valkey or Redis strictly as a cache, configure a
maxmemory-policylikeallkeys-lruso older cached items are cleanly evicted when the container hits its memory ceiling.
Enjoyed this post?
Read more from the blog
