feat: add REDIS_KEY_PREFIX env var for Redis ACL namespace isolation (#365)

* feat: add REDIS_KEY_PREFIX env var for Redis ACL namespace isolation

Adds optional REDIS_KEY_PREFIX env var that prefixes all Redis keys
(BullMQ queues via `prefix` option, cache/lock/rate-limit keys via
`redisKey()` helper). When unset, behavior is unchanged (BullMQ
defaults to "bull:", cache keys are unprefixed).

This enables self-hosters using Redis ACL multi-tenancy to restrict
useSend to its own key namespace (e.g. `~usesend:*`).

16 files changed across env schema, Redis module, 9 BullMQ queue/worker
files, and 5 direct Redis key operation sites.

* docs: add REDIS_KEY_PREFIX to self-host assets and fix docker run example

Add REDIS_KEY_PREFIX env var to docker/prod/compose.yml, .env.example,
.env.selfhost.example, and self-hosting docs. Fix missing trailing
backslashes in standalone docker run example.

* fix(redis): disable ioredis ready check and BullMQ version check

Redis ACL blocks INFO command (in @dangerous category). ioredis uses
INFO for ready check, BullMQ uses it for version detection. Without
these flags, BullMQ workers fail to initialize and silently stop
processing jobs.

- Add enableReadyCheck: false to ioredis connection
- Add skipVersionCheck: true to all 5 Queue + 5 Worker constructors

* fix(redis): add skipVersionCheck to remaining BullMQ job queues

Add skipVersionCheck: true to Queue and Worker constructors in all 4 job
files (campaign-scheduler, cleanup-email-bodies, usage-job,
webhook-cleanup) to match the pattern already used in service files.
This prevents BullMQ version mismatch errors when using REDIS_KEY_PREFIX
with Redis ACL namespace isolation.

Author: designorant

.env.example

@@ -22,4 +22,7 @@ FROM_EMAIL="hello@usesend.com"
 API_RATE_LIMIT=2
 AUTH_EMAIL_RATE_LIMIT=5
 
+# Optional: prefix all Redis keys (useful for shared Redis with ACL isolation)
+# REDIS_KEY_PREFIX=""
+
 NEXT_PUBLIC_IS_CLOUD=true

.env.selfhost.example

@@ -36,5 +36,8 @@ DOCKER_OUTPUT=1
 API_RATE_LIMIT=1
 AUTH_EMAIL_RATE_LIMIT=5
 
+# Optional: prefix all Redis keys (useful for shared Redis with ACL isolation)
+# REDIS_KEY_PREFIX=""
+
 # used to send important error notification - optional
 DISCORD_WEBHOOK_URL=""

apps/docs/self-hosting/overview.mdx

@@ -59,6 +59,8 @@ DATABASE_URL="postgres://<username>:<password>@<host>:<port>/<database-name>"
 REDIS_URL="redis://<username>:<password>@<host>:<port>"
 ```
 
+If you're sharing a Redis instance across multiple apps and using Redis ACL for isolation, set `REDIS_KEY_PREFIX` to namespace all keys (e.g. `REDIS_KEY_PREFIX="usesend"` prefixes all keys with `usesend:`).
+
   </Step>
   <Step title="Next auth url and secret">
   Url is the app url you're going to use and secret is random string. You can generate a random secret using this command.

apps/web/src/app/api/auth/[...nextauth]/route.ts

@@ -2,7 +2,7 @@ import NextAuth from "next-auth";
 
 import { authOptions } from "~/server/auth";
 import { env } from "~/env";
-import { getRedis } from "~/server/redis";
+import { getRedis, redisKey } from "~/server/redis";
 import { logger } from "~/server/logger/log";
 
 const handler = NextAuth(authOptions);
@@ -60,7 +60,7 @@ export async function POST(req: Request, ctx: any) {
           return handler(req, ctx);
         }
         const redis = getRedis();
-        const key = `auth-rl:${ip}`;
+        const key = redisKey(`auth-rl:${ip}`);
         const ttl = 60;
         const count = await redis.incr(key);
         if (count === 1) await redis.expire(key, ttl);

apps/web/src/env.js

@@ -53,6 +53,7 @@ export const env = createEnv({
     FOUNDER_EMAIL: z.string().optional(),
     DISCORD_WEBHOOK_URL: z.string().optional(),
     REDIS_URL: z.string(),
+    REDIS_KEY_PREFIX: z.string().default(""),
     S3_COMPATIBLE_ACCESS_KEY: z.string().optional(),
     S3_COMPATIBLE_SECRET_KEY: z.string().optional(),
     S3_COMPATIBLE_API_URL: z.string().optional(),
@@ -116,6 +117,7 @@ export const env = createEnv({
     FOUNDER_EMAIL: process.env.FOUNDER_EMAIL,
     DISCORD_WEBHOOK_URL: process.env.DISCORD_WEBHOOK_URL,
     REDIS_URL: process.env.REDIS_URL,
+    REDIS_KEY_PREFIX: process.env.REDIS_KEY_PREFIX,
     FROM_EMAIL: process.env.FROM_EMAIL,
     S3_COMPATIBLE_ACCESS_KEY: process.env.S3_COMPATIBLE_ACCESS_KEY,
     S3_COMPATIBLE_SECRET_KEY: process.env.S3_COMPATIBLE_SECRET_KEY,

apps/web/src/server/api/routers/waitlist.ts

@@ -4,7 +4,7 @@ import { env } from "~/env";
 import { authedProcedure, createTRPCRouter } from "~/server/api/trpc";
 import { logger } from "~/server/logger/log";
 import { sendMail } from "~/server/mailer";
-import { getRedis } from "~/server/redis";
+import { getRedis, redisKey } from "~/server/redis";
 import {
   WAITLIST_EMAIL_TYPES,
   waitlistSubmissionSchema,
@@ -40,7 +40,7 @@ export const waitlistRouter = createTRPCRouter({
       }
 
       const redis = getRedis();
-      const rateKey = `waitlist:requests:${user.id}`;
+      const rateKey = redisKey(`waitlist:requests:${user.id}`);
 
       const currentCountRaw = await redis.get(rateKey);
       const currentCount = currentCountRaw ? Number(currentCountRaw) : 0;

apps/web/src/server/jobs/campaign-scheduler-job.ts

@@ -4,7 +4,7 @@ import {
   CAMPAIGN_SCHEDULER_QUEUE,
   DEFAULT_QUEUE_OPTIONS,
 } from "../queue/queue-constants";
-import { getRedis } from "../redis";
+import { getRedis, BULL_PREFIX } from "../redis";
 import { CampaignBatchService } from "../service/campaign-service";
 import { db } from "../db";
 import { logger } from "../logger/log";
@@ -18,6 +18,8 @@ export class CampaignSchedulerService {
     CAMPAIGN_SCHEDULER_QUEUE,
     {
       connection: getRedis(),
+      prefix: BULL_PREFIX,
+      skipVersionCheck: true,
     }
   );
 
@@ -82,7 +84,7 @@ export class CampaignSchedulerService {
         logger.error({ err }, "Campaign scheduler tick failed");
       }
     }),
-    { connection: getRedis(), concurrency: 1 }
+    { connection: getRedis(), concurrency: 1, prefix: BULL_PREFIX, skipVersionCheck: true }
   );
 
   static async start() {

apps/web/src/server/jobs/cleanup-email-bodies.ts

@@ -1,6 +1,6 @@
 import {Queue, Worker} from "bullmq";
 import {db} from "~/server/db";
-import {getRedis} from "~/server/redis";
+import {getRedis, BULL_PREFIX} from "~/server/redis";
 import {logger} from "../logger/log";
 import {DEFAULT_QUEUE_OPTIONS} from "../queue/queue-constants";
 import {env} from "~/env";
@@ -19,6 +19,8 @@ if (isSelfHosted() && isEmailCleanupEnabled()) {
      */
     const cleanupQueue = new Queue(CLEANUP_QUEUE_NAME, {
         connection: getRedis(),
+        prefix: BULL_PREFIX,
+        skipVersionCheck: true,
     });
 
     const worker = new Worker(
@@ -47,6 +49,8 @@ if (isSelfHosted() && isEmailCleanupEnabled()) {
         },
         {
             connection: getRedis(),
+            prefix: BULL_PREFIX,
+            skipVersionCheck: true,
         }
     );
 

apps/web/src/server/jobs/usage-job.ts

@@ -3,14 +3,16 @@ import { db } from "~/server/db";
 import { env } from "~/env";
 import { getUsageDate, getUsageUnits } from "~/lib/usage";
 import { sendUsageToStripe } from "~/server/billing/usage";
-import { getRedis } from "~/server/redis";
+import { getRedis, BULL_PREFIX } from "~/server/redis";
 import { DEFAULT_QUEUE_OPTIONS } from "../queue/queue-constants";
 import { logger } from "../logger/log";
 
 const USAGE_QUEUE_NAME = "usage-reporting";
 
 const usageQueue = new Queue(USAGE_QUEUE_NAME, {
   connection: getRedis(),
+  prefix: BULL_PREFIX,
+  skipVersionCheck: true,
 });
 
 const worker = new Worker(
@@ -69,6 +71,8 @@ const worker = new Worker(
   },
   {
     connection: getRedis(),
+    prefix: BULL_PREFIX,
+    skipVersionCheck: true,
   },
 );
 

apps/web/src/server/jobs/webhook-cleanup-job.ts

@@ -1,14 +1,16 @@
 import { Queue, Worker } from "bullmq";
 import { subDays } from "date-fns";
 import { db } from "~/server/db";
-import { getRedis } from "~/server/redis";
+import { getRedis, BULL_PREFIX } from "~/server/redis";
 import { DEFAULT_QUEUE_OPTIONS, WEBHOOK_CLEANUP_QUEUE } from "../queue/queue-constants";
 import { logger } from "../logger/log";
 
 const WEBHOOK_RETENTION_DAYS = 30;
 
 const webhookCleanupQueue = new Queue(WEBHOOK_CLEANUP_QUEUE, {
   connection: getRedis(),
+  prefix: BULL_PREFIX,
+  skipVersionCheck: true,
 });
 
 const worker = new Worker(
@@ -30,6 +32,8 @@ const worker = new Worker(
   },
   {
     connection: getRedis(),
+    prefix: BULL_PREFIX,
+    skipVersionCheck: true,
   }
 );