Runtime & Storage

Sublink Worker can run on Cloudflare, Node/Vercel, and Docker. To maintain consistent behavior, the runtime is abstracted into three layers: Compute, KV/Redis Storage, and Static Assets. This section outlines environment variables, images, CI strategies, and recommended persistence solutions.

Storage Priority

When the Worker starts, it resolves storage in the following priority order:

1. Redis: Connect via REDIS_URL (redis://user:pass@host:port/db) or REDIS_HOST + REDIS_PORT, suitable for Docker Compose and self-hosted Redis.
2. Upstash/Vercel KV: Provide KV_REST_API_URL and KV_REST_API_TOKEN. Vercel projects can directly reference Vercel KV environment variables.
3. In-Memory KV: Enabled when none of the above are configured, suitable for temporary debugging. If you explicitly don't want fallback, set DISABLE_MEMORY_KV=true.

We recommend always using Redis or Upstash KV in production environments. Config Storage and short links are written to KV, so choosing a backend with persistence capabilities prevents subscription invalidation.

Common Environment Variables

Variable	Description	Default
KV_REST_API_URL / KV_REST_API_TOKEN	Upstash / Vercel KV REST Endpoint + Token	Not set
REDIS_URL	Redis connection URL (highest priority)	Not set
REDIS_HOST / REDIS_PORT	Host/Port format when URL unavailable	Not set
REDIS_USERNAME / REDIS_PASSWORD	Redis authentication credentials	Not set
REDIS_TLS	Enable TLS connection when set to true	false
REDIS_KEY_PREFIX	Key prefix for multi-instance Redis sharing	Not set
CONFIG_TTL_SECONDS	TTL for base configs in KV, default 30 days	2592000
SHORT_LINK_TTL_SECONDS	Short link TTL (if runtime supports)	Never expires
STATIC_DIR	Static assets directory for Node/Vercel runtime	public
DISABLE_MEMORY_KV	Disable in-memory KV fallback	false

All variables can be configured in Cloudflare Workers → Settings → Variables, or written to runtime config in Docker/Vercel environments.

Docker Images & CI

• .github/workflows/docker-image.yml runs on main, any tag push, and manual triggers, building amd64/arm64 dual-architecture images.
• Images are uniformly pushed to ghcr.io/7sageer/sublink-worker, with tags including latest, branch/tag names, and commit SHA for easy rollback.
• When using official Docker images:

docker pull ghcr.io/7sageer/sublink-worker:latest
docker run -p 8787:8787 -e REDIS_HOST=redis -e REDIS_PORT=6379 ghcr.io/7sageer/sublink-worker:latest

• docker-compose.yml starts both Worker and Redis 7, loading redis.conf to enable RDB snapshots. Data is written to the redis-data volume by default and persists after container restarts.
• To debug local code, run docker build -t sublink-worker:dev . and set SUBLINK_WORKER_IMAGE=sublink-worker:dev docker compose up.

Version Management & Sync

• After forking the repository, use GitHub's Sync fork to stay in sync with upstream.
• For production environments, we recommend binding CI, for example:
  • GitHub Actions: Listen to main to trigger custom Workflows, deploying pnpm run build:node results to servers.
  • Cloudflare Pages: Enable Production branch auto-deployment, verify configs in Preview environment before publishing.

Monitoring & Observability Recommendations

• Bind the Worker to a custom domain for easier use of your own monitoring or logging platforms.
• When Redis runs in Docker Compose, observe read/write with redis-cli MONITOR and INFO persistence. If using Upstash, check request statistics in the console.
• We recommend configuring rate limits for write operation endpoints like /shorten and /config (can use Cloudflare Rules).

Next step: Configure custom base configs and KV storage. Read Base Config (Experimental).