minhtudragon/redis_hf

hf-redis-rest

Self-hosted, Upstash-compatible Redis REST server that runs as a Hugging Face Docker Space. Drop-in replacement for Upstash Redis REST — change two env vars and your app keeps working.

Not for production. Data is ephemeral. Use for cache, rate limiting, dev/staging.

What It Does

• —Runs Redis + a REST API inside a single Docker container
• —Accepts Upstash-style JSON Redis commands over HTTPS
• —Bearer-token authentication
• —Pipeline support
• —Health check endpoint

What It Does Not Do

• —No data persistence across Space restarts/rebuilds
• —No Redis Cluster
• —No multi-tenant databases
• —No raw TCP access
• —No full Upstash feature parity
• —Not a replacement for managed Redis in production

Quick Start

Deploy to Hugging Face Spaces

1. 1.Create a new Docker Space on Hugging Face
2. 2.Push this repo to the Space
3. 3.Set the Space secret: REDIS_REST_TOKEN=your-secret-token
4. 4.Wait for the build to complete

Configure Your App

Change your environment variables:

REDIS_URL="https://<your-hf-username>-<space-name>.hf.space"
REDIS_REST_TOKEN="your-secret-token"

That's it. No code changes needed.

Environment Variables

Your App (client side)

Hugging Face Space Secrets

Optional Persistence

Set REDIS_PERSISTENCE=aof in your Space secrets to enable AOF persistence. Warning: free HF Space disk is not guaranteed persistent across rebuilds/restarts. Do not rely on this for data durability.

Testing with curl

Health Check (no auth needed)

curl https://<space>.hf.space/health

Expected:

{"status":"ok","redis":"connected"}

SET / GET

curl -X POST "https://<space>.hf.space" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '["SET","hello","world"]'

curl -X POST "https://<space>.hf.space" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '["GET","hello"]'

Pipeline

curl -X POST "https://<space>.hf.space/pipeline" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '[["SET","a","1"],["GET","a"]]'

Path-Style (optional)

curl "https://<space>.hf.space/get/hello"
curl "https://<space>.hf.space/set/key/value"
curl "https://<space>.hf.space/del/key"

Note: path-style commands also require auth if REDIS_REST_TOKEN is set.

Supported Redis Commands

Phase 1 (fully supported)

GET SET DEL EXISTS EXPIRE TTL INCR DECR MGET MSET HGET HSET HDEL HGETALL LPUSH RPUSH LPOP RPOP LRANGE SADD SREM SMEMBERS ZADD ZREM ZRANGE PING

Phase 2 (supported)

SCAN KEYS FLUSHDB SETEX PSETEX GETDEL GETEX ZCARD ZSCORE ZREVRANGE XADD XREAD

Phase 3 (supported)

SETNX GETSET APPEND STRLEN INCRBY DECRBY EXPIREAT PEXPIRE PTTL PERSIST RENAME TYPE LINDEX LLEN LREM LTRIM HEXISTS HINCRBY HKEYS HVALS HLEN HMGET HMSET SISMEMBER SCARD SDIFF SINTER SUNION ZRANK ZCOUNT ZREMRANGEBYRANK ZREMRANGEBYSCORE SRANDMEMBER SPOP

Blocked Commands

FLUSHALL CONFIG SHUTDOWN SAVE BGSAVE CLIENT MONITOR DEBUG CLUSTER REPLICAOF SLAVEOF REPLCONF PFDEBUG

Local Development

docker build -t hf-redis-rest .
docker run -p 7860:7860 -e REDIS_REST_TOKEN=test-token hf-redis-rest

Test:

curl -X POST http://localhost:7860 \
  -H "Authorization: Bearer test-token" \
  -H "Content-Type: application/json" \
  -d '["PING"]'

Troubleshooting

License

MIT