Self-Hosting Dub - Cloud-Native Link Attribution, Not a Tiny …

Dub is not just a cute short-link app.

It is a link attribution platform: short links, branded domains, click analytics, conversion tracking, API management, webhooks, partner programs, affiliate workflows, and a polished dashboard.

That also means its self-hosting story is very different from a single-container URL shortener.

What is Dub?

Dub is an open-source link attribution platform for creating, managing, tracking, and automating short links.

I inspected commit:

5742f606e8be90ce349d59e3dd8c026df7fbdb84

The repository is a pnpm/Turborepo monorepo centered around apps/web, the main Next.js application.

Licensing Notes

Dub is open-core.

The root package and README identify the public code as:

AGPL-3.0-or-later

The README also notes that code under /ee is covered by a separate commercial license. That is common for open-core SaaS projects, but it is worth knowing before you build commercial workflows around a fork.

What You Get

Dub is interesting if you want more than simple redirects.

Useful features include:

branded short links;
custom domains;
link folders, tags, and API access;
click analytics by country, city, device, browser, OS, referrer, and time;
conversion tracking;
webhooks;
OAuth/API tokens;
partner and affiliate workflows;
importers and integrations;
dashboard and team/workspace management.

For a business-facing link platform, that is compelling. For a personal “I need short links on my VPS” use case, it may be too much infrastructure.

Architecture

Dub’s application is split by workload.

The repo includes:

apps/web: Next.js app, dashboard, API routes, middleware, auth, and redirect logic.
apps/web/prisma/schema: Prisma/MySQL schema split across users, links, domains, workspaces, webhooks, partners, billing, integrations, and related models.
apps/web/lib/upstash: Redis cache, locks, and Redis stream helpers.
apps/web/lib/tinybird: analytics ingestion and query helpers.
apps/web/lib/planetscale: MySQL/PlanetScale edge query helpers.
apps/web/lib/storage: S3-compatible upload/signing logic.
packages/tinybird: Tinybird datasources and pipes.
packages/ui, packages/utils, packages/email, packages/cli, packages/embeds: shared packages and distribution surfaces.

The mental model is:

Browser / API client
  -> Next.js app and middleware
  -> Redis cache for hot link lookups
  -> MySQL for transactional app data
  -> Tinybird / ClickHouse for analytics
  -> QStash for async webhook/background delivery
  -> S3-compatible storage for uploaded/generated assets

The Redirect Path

The short-link path is optimized to avoid hitting the relational database on every click.

From the inspected middleware and cache code, a redirect lookup goes roughly like this:

Parse domain and key from the request.
Normalize the key and reject unsupported paths.
Check an in-process LRU cache.
Check Upstash Redis.
If Redis misses, query MySQL through the PlanetScale client.
Cache the link back into Redis.
Apply password, expiration, disabled, A/B test, app-store, geo, and device rules.
Mint or recover click IDs for attribution.
Record analytics through Tinybird.
Return a redirect, rewrite, not-found page, password page, or inspect page.

There is also a Vercel runtime cache fallback when Redis fails. In that failover mode, Dub can skip click tracking to avoid slowing down the redirect response.

That is a very different design from “request -> SQL row -> redirect.”

Why Tinybird / ClickHouse Exists

Dub separates transactional data from analytics data.

The MySQL database is for users, workspaces, links, domains, tokens, webhooks, folders, tags, partners, payouts, integrations, and similar application state.

Click events are different. They are high-volume, append-heavy, and often queried as aggregates:

clicks by country
clicks by browser
clicks by device
clicks by referrer
timeseries over a date range
conversion events by link or workspace

The packages/tinybird folder contains datasources and pipes for this analytics plane. The inspected click datasource stores fields such as timestamp, click ID, link ID, URL, country, city, device, browser, OS, referrer, user/IP data, QR flag, workspace ID, domain, key, and Vercel region.

That is why Tinybird/ClickHouse is not just decorative. It is the OLAP side of the product.

Why Redis and QStash Exist

Redis sits directly in front of the redirect path.

Dub uses it for hot link metadata, rate limiting, attribution cache, and other fast state. Without that layer, traffic spikes would push far more reads into MySQL.

QStash handles async delivery patterns such as webhook publishing and callbacks. The inspected webhook code prepares a payload, signs it, publishes it through QStash, and registers success/failure callback URLs.

In practical terms:

Redis keeps redirects fast.
QStash keeps background delivery out of the redirect request.

Official Self-Hosting Requirements

Dub’s official self-hosting guide asks you to prepare:

a GitHub account;
a Tinybird account;
an Upstash account;
a PlanetScale account or compatible MySQL path;
a Vercel account;
either Cloudflare or AWS;
a custom domain for the Dub app;
optionally, a separate short domain for links.

That list tells you a lot about the project. Dub was built as an enterprise-scale SaaS application first, then documented for self-hosting by wiring together managed cloud services.

Where Those Accounts Are Used

GitHub is used for source control and OAuth login setup in the self-hosting flow.

Tinybird is used for analytics ingestion and querying. This is the ClickHouse-backed event pipeline for clicks, leads, sales, webhook events, API logs, and usage analytics.

Upstash Redis is used for link caching and low-latency state on the redirect path.

Upstash QStash is used for queues, scheduled/background work, webhook delivery, and callbacks.

PlanetScale / MySQL is the transactional database for core app data.

Vercel is the expected Next.js hosting target. Dub also uses Vercel concepts such as edge/runtime behavior, domain APIs, and runtime cache.

Cloudflare or AWS is mainly relevant for DNS and object storage. The storage client uses S3-style signing, and the official docs describe Cloudflare R2 or AWS S3 for avatars, workspace logos, and generated social card images.

Custom domains are central to the product. You need an app domain for the Dub dashboard and API, and you can configure a short domain for branded links. These domains show up in environment variables, OAuth callback URLs, Vercel domain configuration, and redirect routing.

About Docker

This is the important caveat: Dub is not currently a simple production Docker Compose app.

The repo does include:

apps/web/docker-compose.yml

But that file starts only:

MySQL;
a PlanetScale HTTP simulator;
MailHog.

It is explicitly labeled for local development only.

It does not replace Tinybird, Upstash Redis/QStash, S3/R2, OAuth setup, Vercel domains, or production Next.js hosting.

So I did not try to self-host this one while writing the post. For Dub, endpoint testing against “latest containers” would not prove much unless the managed services and domains were also configured.

Can You Run Local Equivalents?

In theory, yes.

A more self-contained version would need:

MySQL instead of PlanetScale;
Redis instead of Upstash Redis;
ClickHouse plus Tinybird-compatible ingestion/query work, or a rewrite of the analytics layer;
MinIO or another S3-compatible object store instead of R2/S3;
SMTP or Resend for email;
GitHub/Google OAuth credentials or another auth configuration;
a production Next.js host;
domain routing for app and short-link domains.

But that is no longer “just deploy Dub.” That is adapting a cloud-native SaaS architecture into a local platform.

How It Compares to Shlink or Kutt

If your goal is a homelab URL shortener, Dub is probably not the first thing I would deploy.

Shlink and Kutt fit the classic self-hosting shape better: fewer moving pieces, normal database dependencies, and a deployment model that feels natural on a VPS or home server.

Dub makes more sense when you want:

a modern link-management dashboard;
real attribution workflows;
high-volume analytics;
teams and workspaces;
webhooks and API automation;
branded domains at scale;
partner/affiliate workflow features.

That is the tradeoff. Dub gives you a more serious attribution product, but the cost is infrastructure complexity.

FAQ

Is Dub self-hostable?

Yes, but its official path is cloud-native. You are expected to connect external services rather than run one container with one database.

Can I deploy Dub with one Docker Compose file?

Not as a full production deployment today. The repo has a local development Compose file for MySQL, PlanetScale simulation, and MailHog, but that does not cover the full stack.

Does Dub require Tinybird?

For the documented full product, yes. Tinybird is the analytics layer. It handles the high-volume click/conversion event data and the aggregate queries that power the dashboard.

Does Dub require Upstash?

The official setup is built around Upstash Redis and QStash. Redis is important for fast redirect lookups and rate/cache behavior. QStash is used for asynchronous delivery such as webhooks and callbacks.

Can I replace PlanetScale with normal MySQL?

The Prisma schema uses MySQL, and the local development setup uses MySQL with a PlanetScale HTTP simulator. For production, the official guide is written around PlanetScale-style deployment assumptions. Running plain MySQL may be possible, but you should expect to validate the edge connection paths, migrations, pooling, and operational behavior yourself.

Can I replace Cloudflare R2 with AWS S3 or MinIO?

The storage code is S3-compatible, so R2 and S3 are natural fits. MinIO may work for local development if the endpoint and signing behavior match what Dub expects, but it is not the official hosted path.

Why does Vercel matter?

Dub is a Next.js application and uses Vercel-oriented features: deployment conventions, domain APIs, runtime cache, functions, and edge behavior. You can investigate other Next.js hosts, but that becomes platform adaptation work.

Do I need a custom domain?

Yes for a realistic deployment. Dub needs an app domain for the dashboard/API, and the product becomes useful when you also configure a short domain for redirects.

Should I choose Dub for my homelab?

Choose Dub if you want a serious link attribution platform and are comfortable operating several managed services or local equivalents.

Choose a simpler tool if you mainly want private short links with low operational overhead.

Verdict

Dub is impressive, but it is not small.

It is a SaaS-grade link attribution platform with a proper hot redirect path, a separate analytics plane, async job delivery, object storage, OAuth, custom domains, and a modern dashboard.

That architecture is exactly why it can support serious link analytics. It is also why self-hosting Dub is closer to assembling a managed cloud stack than starting a normal homelab container.

Self-Hosting Dub - Cloud-Native Link Attribution, Not a Tiny URL Shortener