Redis

Redis is available as a global service in Stackpanel. Enable it and you get a local Redis instance running on a deterministic port—the same port on every machine, for every team member.

Quick Start

stackpanel.globalServices = {
  enable = true;
  redis.enable = true;
};

That's it. Enter your dev shell and Redis is running. Connect to it using the STACKPANEL_REDIS_PORT environment variable:

redis-cli -p $STACKPANEL_REDIS_PORT ping
# PONG

Connection Details

In your application code, read the port from the environment:

import { createClient } from "redis";

const client = createClient({
  url: `redis://localhost:${process.env.STACKPANEL_REDIS_PORT}`,
});

await client.connect();

Or in Go:

import "github.com/redis/go-redis/v9"

client := redis.NewClient(&redis.Options{
    Addr: fmt.Sprintf("localhost:%s", os.Getenv("STACKPANEL_REDIS_PORT")),
})

Configuration

Custom Settings

You can pass additional configuration to the Redis instance:

stackpanel.globalServices = {
  enable = true;
  redis = {
    enable = true;
    # Additional Redis configuration options
  };
};

Data Persistence

By default, Redis data is stored in a project-local directory managed by Stackpanel. Data persists across shell sessions but is local to your machine—it's not shared between team members.

To start fresh, stop the service and remove the data directory:

stackpanel services stop redis
rm -rf .stack/state/redis/
stackpanel services start redis

Managing the Service

Use the Stackpanel CLI or Studio to manage the Redis lifecycle:

# Check status
stackpanel services status

# Stop Redis
stackpanel services stop redis

# Restart Redis
stackpanel services restart redis

# View logs
stackpanel logs redis

You can also manage services through Studio, which provides a visual interface for starting, stopping, and monitoring all your services.

Using with Other Services

Redis pairs naturally with other Stackpanel services. A common pattern is running Redis alongside PostgreSQL for caching:

stackpanel.globalServices = {
  enable = true;
  postgres.enable = true;
  redis.enable = true;
};

Both services get deterministic ports, and both are available through environment variables. Your application can reference them without any manual port coordination.

Environment Variables

When Redis is enabled, the following environment variables are available in your devshell:

Use these in your .env templates, scripts, or application code to stay in sync with the running service.

Troubleshooting

"Connection refused" errors

Make sure the service is running:

stackpanel services status

If Redis shows as stopped, start it:

stackpanel services start redis

Port conflicts

Stackpanel's deterministic port system makes conflicts unlikely, but if another process is already using the computed port, Redis will fail to start. Check what's using the port:

lsof -i :$STACKPANEL_REDIS_PORT

Stale data causing issues

If you need a clean slate:

stackpanel services stop redis
rm -rf .stack/state/redis/
stackpanel services start redis

Reference

• Options Reference → GlobalServices for all service configuration options
• Deterministic Ports for how ports are computed
• Services Overview for general service management