upstash-redis-local

A local webserver for testing and development using @upstash/redis

📖 Full Documentation → | Preview locally: cd docs && mint dev

🤔 What is upstash-redis-local?

The upstash-redis-local command starts a local web server that provides a REST API compatible with Upstash REST API. It connects to a real Redis database instance, making it perfect for local development and testing.

Key Features:

✅ Compatible with @upstash/redis SDK
✅ Unlimited local requests — no cloud rate limits or daily quotas
✅ Full REST API: /pipeline, /multi-exec, /publish, /subscribe, /monitor
✅ Read-only token support (like Upstash cloud)
✅ Usage dashboard at /dashboard — see cloud quota saved
✅ Rate-limit simulator (--simulate-quota, --simulate-rps)
✅ QStash emulator — local HTTP message queue with delays, retries, DLQ (--enable-qstash)
✅ Chaos injection — simulate slow/flaky Upstash (--inject-latency, --inject-error-rate)
✅ Cloud-parity strict mode — catch "works locally, breaks in prod" (--strict-upstash)
✅ Record & replay — capture a session and replay it (--record, upstash-local replay)
✅ Security hardening: --secure, dashboard auth, dangerous-command blocking
✅ CORS enabled for browser/edge dev
✅ Docker Compose profiles: default, external Redis, Redis Stack
✅ CLI tools: upstash-local use dev, seed, export, import, generate-token, replay
✅ Connection pooling + graceful shutdown
✅ Tiny Docker image (~10MB)

This project is inspired by upstashdis but uses fasthttp for better performance.

💻 Usage

upstash-redis-local v1.0
A local server that mimics upstash-redis for local testing purposes!

       * Connect to any local redis of your choice for testing
       * Completely mimics the upstash REST API https://docs.upstash.com/redis/features/restapi

USAGE:
    upstash-redis-local
    upstash-redis-local --token upstash --addr :8000 --redis :6379

ARGUMENTS:
    --token       TOKEN  The API token to accept as authorised (default: upstash)
    --addr        ADDR   Address for the server to listen on (default: :8000)
    --redis       ADDR   Address to your redis server (default: :6379)
    --max-retries N      Max connection retries on startup (default: 10)
    --retry-delay MS     Delay between retries in milliseconds (default: 1000)
    --help               Prints this message

ENVIRONMENT VARIABLES:
    REDIS_ADDR     Redis server address (alternative to --redis)
    UPSTASH_ADDR   Webserver address (alternative to --addr)
    UPSTASH_TOKEN  API token (alternative to --token)

🚀 Quick Start

chmod +x start.sh
./start.sh

Then open:

REST API: http://localhost:8000/PING?_token=local-dev-token
Dashboard: http://localhost:8000/dashboard
Health: http://localhost:8000/health

Switch your app to local (no rate limits)

make build-cli
./bin/upstash-local use dev
# Point your app at .env.local — unlimited requests, zero cloud quota

See .env.example for cloud vs local profiles.

📊 Dashboard & Rate Limit Tools

Open http://localhost:8000/dashboard to see:

Total requests (unlimited locally)
Cloud quota saved vs Upstash free tier (10k/day)
Key browser

Simulate cloud limits for testing fallback logic:

upstash-redis-local --simulate-quota 10000 --simulate-rps 100

🧪 Testing & Reliability Tools

# Simulate a slow, flaky Upstash (test your retry/fallback logic)
upstash-redis-local --inject-latency 200 --inject-error-rate 0.1

# Reject commands Upstash REST doesn't support (catch prod bugs early)
upstash-redis-local --strict-upstash

# Record every command, then replay the session later
upstash-redis-local --record session.jsonl
./bin/upstash-local replay --input session.jsonl

See docs/guides/testing-tools.mdx.

📨 QStash Emulator

A local HTTP message queue (like Upstash QStash) for background jobs, webhooks, and email/notification queues:

upstash-redis-local --enable-qstash

# Queue a message for delivery to a URL (with retries + DLQ)
curl -X POST "http://localhost:8000/v2/publish/?url=https://example.com/webhook" \
  -H "Authorization: Bearer local-dev-token" \
  -H "Upstash-Delay: 10s" \
  -d '{"email":"welcome@app.com"}'

curl http://localhost:8000/v2/messages -H "Authorization: Bearer local-dev-token"
curl http://localhost:8000/v2/dlq -H "Authorization: Bearer local-dev-token"

See docs/guides/qstash.mdx.

🔧 CLI Commands

make build-cli
./bin/upstash-local use dev      # Switch to local (unlimited)
./bin/upstash-local use cloud    # Switch to cloud (.env.cloud required)
./bin/upstash-local status       # Show active profile
./bin/upstash-local seed --keys 1000 --prefix dev:
./bin/upstash-local export --output dump.json
./bin/upstash-local import --input dump.json
./bin/upstash-local ping

🐳 Docker Compose Profiles

# Default — bundled Redis
docker compose up -d

# External Redis (when port 6379 already in use)
docker compose --profile external up -d upstash-local-external

# Redis Stack (JSON module support)
docker compose --profile stack up -d

⬇ Installation

Using Docker Compose (Recommended)

The easiest way to get started:

# Clone the repository
git clone https://github.com/aine1100/Upstash-Redis-Local-server.git
cd upstash-redis-local

# Start Redis and upstash-redis-local
docker-compose up -d

# Test the connection
curl -H "Authorization: Bearer local-dev-token" http://localhost:8000/PING

Quick Start (Automated Script)

On Windows (Git Bash/WSL), macOS, or Linux, you can use the provided startup script:

chmod +x start.sh
./start.sh

This script will:

Check if Docker is running.
Attempt to start Docker Desktop if it's closed.
Start the containers using docker-compose up -d.

Using Docker

# Run with a local Redis
docker run --rm -p 8000:8000 darthbenro008/upstash-redis-local:latest --redis host.docker.internal:6379

# Or link to a Redis container
docker run -d --name redis redis:7-alpine
docker run --rm -p 8000:8000 --link redis:redis darthbenro008/upstash-redis-local:latest --redis redis:6379

Using Homebrew

brew tap aine1100/Upstash-Redis-Local-server
brew install upstash-redis-local

Building from Source

# Clone and build
git clone https://github.com/aine1100/Upstash-Redis-Local-server.git
cd upstash-redis-local
make build

# Run
./bin/upstash-redis-local --redis :6379

Manual Installation

Download the latest release from the releases page for your OS.

🔐 Authentication

The server requires an API token to authorize requests. By default, this token is local-dev-token (when using Docker Compose) or upstash.

1. In the Browser

Append the _token query parameter to your URL: http://localhost:8000/PING?_token=local-dev-token

2. In the API Tool (Postman)

URL: http://localhost:8000/KEYS/*
Auth Type: Select API Key
Key: _token
Value: local-dev-token
Add to: Query Params (Recommended)

3. Using cURL

curl -H "Authorization: Bearer local-dev-token" http://localhost:8000/PING
# OR
curl "http://localhost:8000/PING?_token=local-dev-token"

🔧 Using with @upstash/redis

import { Redis } from '@upstash/redis'

const redis = new Redis({
  url: 'http://localhost:8000',
  token: 'local-dev-token', // or your custom token
})

// Use normally
await redis.set('foo', 'bar')
const value = await redis.get('foo')
console.log(value) // 'bar'

🐳 Docker Compose Configuration

The included docker-compose.yml provides:

Redis 7 with health checks
upstash-redis-local with automatic retry
Persistent Redis data volume

services:
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
  
  upstash-local:
    build: .
    ports:
      - "8000:8000"
    environment:
      - REDIS_ADDR=redis:6379
      - UPSTASH_TOKEN=local-dev-token
    depends_on:
      redis:
        condition: service_healthy

🔍 Viewing the Database

There are several ways to view and manage your local data:

1. Using Redis CLI (Inside Docker)

You can jump into the Redis container to run raw commands:

docker exec -it upstash-redis-local-redis-1 redis-cli
# Then try:
> keys *
> get foo

2. Using Redis Insight (GUI)

Redis Insight is a free, powerful GUI for Redis.

Host: localhost
Port: 6379
Password: (none by default)

3. Using HTTP Requests

Since this project mimics Upstash, you can just use your browser or curl:

Get all keys: http://localhost:8000/KEYS/*?_token=local-dev-token
Get value: http://localhost:8000/GET/mykey?_token=local-dev-token

Note

If you see random strings like "YnVsb0...", it means you were viewing raw bytes. This has been fixed to return readable strings.

🔍 Troubleshooting

Connection Refused

If you see connection refused errors:

Ensure Redis is running: redis-cli ping
Check the address format: --redis localhost:6379 (not just :6379)
In Docker, use the service name: --redis redis:6379

Docker Networking

When running in Docker, use:

host.docker.internal:6379 to connect to Redis on host machine
The service name (e.g., redis:6379) when using Docker Compose

🤝 Contributions

Feel free to open a PR/Issue for any feature or bug(s)
Follow the community guidelines
See CONTRIBUTING.md for development setup

⚖ License

Licensed under MIT License: https://opensource.org/licenses/MIT

Made with ❤ and a single cup of kofi

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
.github/workflows		.github/workflows
assets		assets
cmd/upstash-local		cmd/upstash-local
docs		docs
internal		internal
scripts		scripts
.atlas-analysis.json		.atlas-analysis.json
.env.example		.env.example
.gitignore		.gitignore
.goreleaser.yaml		.goreleaser.yaml
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum
main.go		main.go
readme.md		readme.md
start.sh		start.sh

Folders and files

Latest commit

History

Repository files navigation