Table of Contents

Dub 사용법 2026: 오픈소스 링크 어트리뷰션 플랫폼 셀프호스팅 가이드

Q: Dub 사용법을 처음 익힐 때 무엇부터 해야 하나요?

가장 먼저 링크 하나를 API로 만들어보고 shortLink가 생성되는지 확인하는 것이 좋습니다. 그다음 conversion tracking을 켜고 lead 또는 sale 이벤트를 어디에서 보낼지 정하세요.

Q: Dub 셀프호스팅은 Docker Compose만 있으면 되나요?

아닙니다. local development용 Docker Compose는 있지만 production self-hosting은 Tinybird, Upstash, PlanetScale, Vercel Domains API, Cloudflare R2 또는 AWS, Resend 같은 외부 인프라가 필요합니다.

Q: Bitly 대신 Dub를 써도 되나요?

단순 클릭 분석만 필요하면 Bitly 같은 관리형 도구가 더 간단할 수 있습니다. Dub는 전환 추적, API 자동화, 파트너 프로그램, 오픈소스 코드 접근이 중요할 때 더 잘 맞습니다.

Dub 사용법을 짧은 링크 생성으로만 보면 절반만 보는 것입니다. Dub는 링크를 만들고, 클릭을 분석하고, 전환 이벤트를 붙이고, 파트너·추천 프로그램까지 운영하는 링크 어트리뷰션 플랫폼입니다.

Dub 사용법: 오픈소스 링크 어트리뷰션 플랫폼 공식 README 이미지 — Dub는 짧은 링크, 전환 추적, 제휴 프로그램을 한 플랫폼에서 다룹니다.

이 글은 Dub를 “Bitly 대체재” 정도로 소개하지 않습니다. 실제로 어떤 문제를 풀 수 있는지, API로 링크를 만드는 가장 짧은 흐름, 오픈소스 저장소를 로컬에서 살펴볼 때 확인해야 할 파일, 셀프호스팅 전에 필요한 외부 인프라까지 정리합니다.

확인일은 2026년 7월 20일입니다. GitHub API 기준 dubinc/dub는 TypeScript 기반 저장소이며, 24,107 stars와 3,146 forks를 기록했습니다. 공식 README는 Dub가 월 1억 회 이상 클릭과 200만 개 이상 링크를 처리한다고 설명합니다.

먼저 결론

Dub는 마케팅 링크를 많이 다루는 팀에게 잘 맞습니다. 단축 URL 하나를 만드는 것보다 “이 링크가 어떤 캠페인에서 왔고, 어떤 사용자가 가입했고, 매출로 이어졌는지”까지 보려는 경우에 가치가 큽니다.

가장 잘 맞는 사용자는 이런 팀입니다.

뉴스레터, 광고, 파트너 링크를 많이 만든다.
UTM과 짧은 링크가 여러 도구에 흩어져 관리된다.
클릭 수뿐 아니라 lead, sale 같은 전환 이벤트를 보고 싶다.
제휴·추천 프로그램을 직접 운영하거나 곧 운영할 계획이 있다.
API로 링크를 대량 생성하고 내부 대시보드에 분석을 붙이고 싶다.
오픈소스 코드를 확인하거나 일부 기능을 직접 호스팅해야 한다.

반대로 단순히 개인 블로그 링크 몇 개를 줄이는 정도라면 Dub는 과할 수 있습니다. 무료 단축 URL 서비스나 간단한 리다이렉트 테이블로 충분한 경우도 많습니다.

Dub 관련 글도 같이 보기

오픈소스 도구를 실제 운영 환경에 붙이는 흐름을 더 보고 싶다면 아래 글도 함께 참고할 만합니다.

Zappa 사용법 2026: Python 웹앱 AWS Lambda 서버리스 배포 가이드 — 오픈소스 웹앱 배포와 운영 체크리스트
k-skill 사용법: 한국 생활 자동화를 AI 에이전트에게 맡기기 전 확인할 것 — API·자동화 도구를 실사용 환경에 붙일 때의 검증 관점
Humanize KR 사용법: 한글 AI 티 제거기 im-not-ai 설치와 활용 팁 — 오픈소스 도구를 설치 전 검증하는 방식

Dub 사용법 빠른 시작

Dub 사용법을 가장 짧게 확인하려면 호스팅된 Dub에서 워크스페이스를 만들고 API key를 발급한 뒤 링크 하나를 생성해보면 됩니다. 서버에서 실행하는 키는 DUB_API_KEY처럼 환경 변수로 보관합니다.

export DUB_API_KEY="dub_xxxxxxxx"

curl --request POST \
  --url https://api.dub.co/links \
  --header "Authorization: Bearer $DUB_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"url":"https://example.com","trackConversion":true}'

정상이라면 응답에는 링크 ID, 원본 URL, 도메인, slug, shortLink 같은 값이 포함됩니다. 이 단계에서 볼 것은 세 가지입니다.

우리 팀이 링크를 어떤 기준으로 만들 것인가.
전환 추적을 링크 단위로 켤 것인가, 워크스페이스 기본값으로 켤 것인가.
링크 생성 주체가 사람인지, 서버 API인지, 배치 작업인지.

TypeScript SDK를 쓰면 같은 작업을 코드 안에서 처리할 수 있습니다.

npm install dub

import { Dub } from "dub";

const dub = new Dub({
  token: process.env.DUB_API_KEY,
});

const link = await dub.links.create({
  url: "https://example.com",
  trackConversion: true,
});

console.log(link.shortLink);

공식 문서 기준 Dub API는 HTTPS REST API이며, 인증은 Authorization: Bearer ... 헤더를 사용합니다. 서버용 API key는 백엔드에서만 써야 하고, 브라우저에 노출하면 안 됩니다.

Dub는 무엇을 해결하나

마케팅 링크 관리는 처음에는 단순합니다. 캠페인마다 링크를 하나씩 만들고, 클릭 수를 보면 됩니다. 그런데 채널이 늘어나면 문제가 생깁니다.

광고, 뉴스레터, 파트너 링크가 서로 다른 도구에서 만들어진다.
UTM 규칙이 사람마다 달라진다.
링크 클릭은 보이는데 가입·결제와 연결되지 않는다.
파트너별 성과를 계산하려면 스프레드시트가 필요해진다.
내부 제품에서 링크를 자동 생성하려면 별도 API가 필요하다.

Dub는 이 지점을 한 플랫폼으로 묶습니다. 공식 문서가 설명하는 핵심 기능은 short links, marketing attribution, real-time analytics, event webhooks, partner programs, REST API와 SDK입니다.

정리하면 Dub는 “짧은 URL 생성기”라기보다 링크를 중심으로 한 성장·어트리뷰션 인프라에 가깝습니다.

저장소와 패키지 확인 결과

로컬에서 저장소를 clone하고 주요 파일을 확인했습니다. 전체 앱 실행은 하지 않았습니다. 이유는 Dub 로컬 실행에 Tinybird, Upstash, PlanetScale 호환 MySQL, NextAuth secret 등 외부 계정과 비밀값이 필요하기 때문입니다.

git clone --depth 1 https://github.com/dubinc/dub.git /tmp/dub-research
cd /tmp/dub-research
node -v
pnpm -v

이 환경에서 확인된 버전은 다음과 같습니다.

node v22.23.1
pnpm 9.15.4

README의 권장 버전은 Node v23.11.0, pnpm 9.15.9입니다. 실제 로컬 개발을 시작한다면 이 차이를 먼저 맞추는 편이 좋습니다.

항목	확인 내용
저장소	`dubinc/dub`
주 언어	TypeScript
GitHub stars / forks	24,107 / 3,146
기본 브랜치	`main`
모노레포	Turborepo + pnpm workspace
웹앱	`apps/web`
주요 패키지	`packages/cli`, `packages/embeds`, `packages/ui`, `packages/utils`, `packages/tinybird`
웹 프레임워크	Next.js 15.5.8, React 19.1.3
웹앱 라이선스	`apps/web/package.json` 기준 AGPL-3.0-or-later
라이선스 구조	대부분 AGPLv3, 일부 Enterprise Edition 경로는 상업 라이선스

npm registry도 확인했습니다.

패키지	확인 버전	용도
`dub`	0.73.1	TypeScript 서버 SDK
`@dub/analytics`	0.0.32	클라이언트 전환 추적 SDK
`@dub/embed-react`	0.0.18	React embedded dashboard 구성요소
`@dub/embed-core`	0.0.18	Vanilla JS embed core

저장소 안의 packages/cli/package.json에는 dub-cli 패키지도 있습니다. 설명은 “A CLI for easily shortening URLs with the Dub API”이며, binary 이름은 dub입니다. 다만 npm에서 @dub/cli는 확인되지 않았고, 저장소 패키지명은 dub-cli였습니다.

API로 짧은 링크 만들기

Dub API의 기본 URL은 다음입니다.

https://api.dub.co

링크 생성에서 필수값은 원본 URL입니다. 전환 추적까지 같이 보고 싶다면 trackConversion을 켭니다.

curl --request POST \
  --url https://api.dub.co/links \
  --header "Authorization: Bearer $DUB_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/pricing",
    "trackConversion": true
  }'

운영 코드에 넣을 때는 API key 권한을 줄이는 편이 안전합니다. 공식 인증 문서는 API key 권한을 All permissions, Read only, Restricted로 나눕니다. 링크 생성만 하는 서버라면 모든 권한을 줄 이유가 없습니다.

실무에서는 링크를 만들 때 최소한 아래 값을 함께 설계하세요.

설계 항목	왜 필요한가
destination URL	사용자가 최종 도착할 주소
domain/key 규칙	사람이 링크만 봐도 캠페인을 추정할 수 있게 함
UTM 규칙	Google Analytics, 광고 플랫폼과 맞추기 위함
conversion tracking	클릭 이후 가입·구매까지 연결하기 위함
external ID	내부 DB의 캠페인/파트너/사용자와 매칭하기 위함

링크를 만들 수 있다고 바로 자동화를 넓히지는 마세요. 먼저 캠페인 이름, UTM, slug 규칙을 정해야 나중에 분석 데이터가 지저분해지지 않습니다.

전환 추적을 붙일 때 보는 순서

Dub의 강점은 링크 클릭에서 끝나지 않는다는 점입니다. 공식 server-side tracking 문서는 전환 추적 흐름을 다음처럼 안내합니다.

링크 또는 워크스페이스에서 conversion tracking을 켭니다.
웹사이트에 Dub Analytics script를 설치합니다.
서버 측 SDK를 설치합니다.
lead 또는 sale 이벤트를 서버에서 보냅니다.
Dub에서 전환 데이터를 확인합니다.

여기서 중요한 것은 “서버 측 이벤트”입니다. 결제 완료, 회원가입 완료처럼 신뢰해야 하는 이벤트는 브라우저에서만 보내면 누락되거나 조작될 수 있습니다. 공식 문서도 server-side tracking을 권장합니다.

예를 들어 SaaS 가입 전환을 본다면 흐름은 이렇게 잡을 수 있습니다.

사용자 클릭 → dub_id query parameter 저장 → 회원가입 완료 → 서버에서 lead 이벤트 전송 → 캠페인/파트너별 성과 확인

전자상거래라면 sale 이벤트에 주문 금액과 고객 식별자를 함께 보내야 합니다. 환불이나 부정 주문까지 처리하려면 이벤트 수정·삭제 정책도 미리 정해야 합니다.

Dub 셀프호스팅 전에 알아둘 구조

Dub 셀프호스팅은 단순히 Docker Compose 하나 올리는 작업이 아닙니다. 공식 self-hosting 문서는 여러 외부 서비스를 요구합니다.

구성요소	역할
Tinybird / ClickHouse	클릭 이벤트와 분석 데이터 저장
Upstash Redis	링크 메타데이터 캐시, 빠른 redirect 처리
Upstash QStash	큐와 백그라운드 작업
PlanetScale 호환 MySQL	핵심 애플리케이션 데이터베이스
Vercel Domains API	커스텀 도메인 추가·삭제
Cloudflare R2 또는 AWS	이미지·파일 스토리지
Resend	이메일 로그인과 알림 이메일
GitHub OAuth	로그인 provider 중 하나

즉 “데이터를 직접 통제하고 싶다”는 이유만으로 셀프호스팅을 시작하면 생각보다 일이 큽니다. 분석 파이프라인, 캐시, 도메인, 이메일, 스토리지까지 운영해야 합니다.

셀프호스팅을 검토할 때는 아래 질문에 먼저 답해야 합니다.

우리에게 Dub Cloud가 해결하지 못하는 요구사항이 있는가?
AGPLv3 의무와 Enterprise Edition 라이선스 경계를 이해했는가?
Tinybird, Redis, MySQL, 이메일, 스토리지를 운영할 사람이 있는가?
링크 redirect 장애가 곧 매출 손실로 이어질 수 있다는 점을 감당할 수 있는가?
커스텀 도메인과 SSL 발급·갱신을 자동화할 수 있는가?

개인 프로젝트라면 보통 Dub Cloud 또는 간단한 API 사용부터 시작하는 편이 낫습니다. 셀프호스팅은 데이터/브랜딩/컴플라이언스 요구가 분명할 때 검토하세요.

로컬 개발 환경 체크리스트

공식 local development 문서는 Dub가 Turborepo 기반 모노레포라고 설명합니다. 구조는 크게 apps/web과 packages/*로 나뉩니다.

로컬 개발의 기본 흐름은 다음입니다.

git clone https://github.com/dubinc/dub.git
cd dub
pnpm i
pnpm -r --filter "./packages/**" build
cd apps/web
cp .env.example .env

apps/web/.env.example를 보면 필수 환경 변수가 많습니다. 시작 전에 적어도 아래 값은 확인해야 합니다.

NEXTAUTH_SECRET
NEXTAUTH_URL=http://localhost:8888
CRON_SECRET
ENCRYPTION_KEY
DATABASE_URL
PLANETSCALE_DATABASE_URL
UPSTASH_REDIS_REST_URL
UPSTASH_REDIS_REST_TOKEN
QSTASH_TOKEN
TINYBIRD_API_KEY
TINYBIRD_API_URL
TEAM_ID_VERCEL
VERCEL_API_KEY
RESEND_API_KEY

로컬 개발용 Docker Compose는 apps/web/docker-compose.yml에 있습니다. 이 파일은 production용이 아니라 local development용이라고 명시되어 있습니다. 포함된 서비스는 MySQL 8.0, PlanetScale HTTP simulator, Mailhog입니다.

cd apps/web
docker compose up -d
pnpm prisma:push
pnpm run script dev/seed
pnpm dev

공식 문서 기준 개발 서버는 http://localhost:8888에서 열립니다. Google OAuth가 localhost subdomain을 허용하지 않기 때문에 app.localhost:8888 대신 localhost:8888을 쓴다고 설명합니다.

처음 실행 전에는 pnpm dev를 바로 치기보다 아래 순서로 확인하는 편이 좋습니다.

node -v
pnpm -v
docker compose ps
cd apps/web
cp .env.example .env

README가 권장하는 Node/pnpm 버전과 다르면 먼저 맞추세요. 이번 확인 환경은 Node v22.23.1, pnpm 9.15.4였고, README 권장값은 Node v23.11.0, pnpm 9.15.9였습니다.

Bitly, 자체 단축 URL, Dub 비교

Dub를 도입할지 판단하려면 “단축 URL이 필요한가”보다 “어트리뷰션 운영이 필요한가”를 봐야 합니다.

상황	더 맞는 선택
개인이 링크 몇 개만 줄임	간단한 단축 URL 서비스
브랜드 도메인으로 링크를 만들고 클릭만 봄	Bitly 같은 관리형 도구
내부 제품에서 API로 링크를 대량 생성	Dub API 또는 자체 구현
클릭 이후 가입·결제까지 연결	Dub
제휴·추천 프로그램 운영	Dub Partners 계열 기능 검토
데이터와 코드 통제 필요	Dub 셀프호스팅 검토
인프라 운영 여력이 거의 없음	셀프호스팅보다 Dub Cloud 우선

자체 단축 URL을 만드는 것도 가능합니다. 데이터베이스에 slug → url 테이블을 만들고 redirect하면 됩니다. 하지만 전환 추적, 분석 차원, 웹훅, 파트너 정산, SDK까지 붙이기 시작하면 직접 만든 도구가 금방 커집니다.

Dub는 이 확장 지점까지 미리 염두에 둔 선택지입니다. 그래서 단순 링크 축약만 필요할 때는 무겁고, 마케팅 어트리뷰션까지 필요할 때는 매력적입니다.

도입 전에 정해야 할 운영 규칙

Dub를 팀에 넣을 때는 도구보다 규칙이 먼저입니다.

1. 링크 이름 규칙

slug가 아무렇게나 만들어지면 분석이 어려워집니다.

권장 예시: product-launch-2026
피할 예시: test1, newsletter2, abc

캠페인, 채널, 날짜, 국가 같은 값을 어디까지 slug에 넣을지 정하세요. 모든 정보를 slug에 넣을 필요는 없습니다. 하지만 사람이 링크만 보고도 최소한의 의미를 알 수 있어야 합니다.

2. UTM 규칙

광고·뉴스레터·파트너 링크가 섞이면 UTM 규칙이 중요해집니다.

utm_source = newsletter | google | partner-name
utm_medium = email | cpc | affiliate
utm_campaign = launch-2026-q3

UTM과 Dub link metadata가 서로 충돌하지 않도록 한쪽을 기준으로 삼아야 합니다.

3. API key 권한

서버 자동화에 쓰는 API key는 최소 권한으로 만드세요. 링크 생성 전용 배치 작업이 workspace 전체 권한을 가질 필요는 없습니다.

4. 전환 이벤트 기준

lead와 sale을 언제 보낼지 정해야 합니다.

lead: 이메일 인증 완료 또는 회원가입 완료
sale: 결제 성공 webhook 처리 완료
refund: 결제 취소 webhook 처리 완료

이 기준이 흔들리면 캠페인 성과도 흔들립니다.

문제 해결

401 unauthorized가 나온다

API key가 없거나 잘못된 경우입니다. 서버 환경 변수에 들어간 값을 확인하세요. API key는 dub_xxxxxxxx 형식이며, 브라우저에 노출하면 안 됩니다.

printenv DUB_API_KEY

값 자체를 로그에 찍는 것은 피하세요. 배포 환경에서는 secret manager를 쓰는 편이 안전합니다.

429 rate_limit_exceeded가 나온다

Dub API는 rate limit을 적용합니다. 대량 링크 생성은 배치 크기와 재시도 간격을 조절해야 합니다. 공식 API에는 bulk create endpoint도 있으므로, 한 건씩 반복 호출하기 전에 bulk endpoint를 먼저 검토하세요.

로컬에서 `/api/workspaces/[idOrSlug]` 500 에러가 난다

공식 local development 문서의 troubleshooting에 이 항목이 있습니다. 대개 데이터베이스 schema, seed data, 환경 변수 누락을 먼저 의심해야 합니다.

cd apps/web
pnpm prisma:push
pnpm run script dev/seed

그래도 실패하면 .env의 DATABASE_URL, PLANETSCALE_DATABASE_URL, NEXTAUTH_SECRET, NEXTAUTH_URL을 다시 확인하세요.

링크 redirect가 느리다

Dub의 redirect는 Redis 캐시를 중요하게 씁니다. 자체 호스팅에서 redirect가 느리다면 MySQL만 볼 것이 아니라 Upstash Redis 응답 시간, 캐시 hit 여부, edge middleware 경로를 같이 봐야 합니다.

셀프호스팅 배포 후 이메일 로그인이 안 된다

Resend 또는 SMTP 설정을 확인하세요. 로컬 개발에서는 Mailhog를 쓰지만, 실제 배포에서는 메일 발송 provider와 도메인 인증이 필요합니다.

라이선스가 헷갈린다

저장소의 LICENSE.md를 직접 읽어야 합니다. 확인일 기준 대부분은 AGPLv3이고, apps/web/app/(ee) 등 일부 Enterprise Edition 경로는 별도 상업 라이선스 범위로 안내되어 있었습니다. 외부 사용자가 접근하는 수정 버전을 운영한다면 AGPL 의무를 가볍게 보면 안 됩니다.

Dub를 쓰면 좋은 경우

Dub는 마케팅과 제품 데이터가 만나는 지점에서 힘이 납니다.

캠페인 링크가 많고, 링크 생성 자동화가 필요하다.
광고·뉴스레터·파트너 채널별 성과를 한곳에서 보고 싶다.
클릭 수가 아니라 가입, 구매, 환불까지 추적해야 한다.
고객이나 파트너에게 embedded dashboard를 제공하고 싶다.
API와 SDK로 내부 제품에 링크 생성을 붙여야 한다.
오픈소스 코드를 검토하고 필요하면 직접 호스팅해야 한다.

Dub를 천천히 봐도 되는 경우

아래에 해당하면 바로 도입하지 않아도 됩니다.

한 달에 만드는 링크가 몇 개 없다.
클릭 수만 보면 충분하다.
서버 측 전환 추적을 붙일 개발 리소스가 없다.
셀프호스팅을 원하지만 Tinybird, Redis, MySQL, 이메일 운영 경험이 없다.
AGPL 계열 라이선스 검토가 부담스럽다.

이런 경우에는 관리형 서비스로 작게 시작하고, 전환 추적이나 API 자동화가 실제 병목이 될 때 Dub를 검토하는 편이 낫습니다.

FAQ

Dub 사용법을 처음 익힐 때 무엇부터 해야 하나요?

가장 먼저 링크 하나를 API로 만들어보고, shortLink가 생성되는지 확인하세요. 그다음 conversion tracking을 켜고 lead 또는 sale 이벤트를 어디에서 보낼지 정하는 순서가 좋습니다.

Dub는 무료인가요?

GitHub 저장소는 오픈소스이지만, Dub Cloud 요금제와 self-hosting 운영 비용은 별개입니다. 셀프호스팅을 해도 Tinybird, Upstash, PlanetScale 호환 MySQL, 이메일, 스토리지 같은 인프라 비용이 생길 수 있습니다.

Dub 셀프호스팅은 Docker Compose만 있으면 되나요?

아닙니다. 저장소에는 local development용 Docker Compose가 있지만 production self-hosting은 Tinybird, Upstash, PlanetScale, Vercel Domains API, Cloudflare R2 또는 AWS, Resend 등 여러 서비스를 준비해야 합니다.

Bitly 대신 Dub를 써도 되나요?

브랜드 단축 링크와 클릭 분석만 필요하다면 Bitly 같은 관리형 도구가 더 간단할 수 있습니다. Dub는 전환 추적, API 자동화, 파트너 프로그램, 오픈소스 코드 접근이 중요할 때 더 잘 맞습니다.

API key는 프론트엔드에 넣어도 되나요?

서버용 API key는 프론트엔드에 넣으면 안 됩니다. 공식 인증 문서도 API key를 backend only로 다룹니다. 클라이언트 측 추적에는 publishable key나 클라이언트 SDK 문서를 별도로 확인해야 합니다.

로컬에서 Dub 전체 앱을 바로 실행할 수 있나요?

가능은 하지만 준비할 것이 많습니다. 이번 확인에서는 저장소 clone과 파일 검토, npm metadata 확인까지만 수행했고 전체 앱 실행은 하지 않았습니다. Tinybird, Upstash, PlanetScale 호환 DB, NextAuth secret 등 실제 계정과 비밀값이 필요하기 때문입니다.

마무리

Dub는 링크를 줄이는 도구로 시작해서 보면 조금 무겁습니다. 하지만 링크가 매출과 파트너 성과로 이어지는 팀이라면 이야기가 달라집니다. 링크 생성, 전환 추적, 실시간 분석, 파트너 프로그램, API 자동화가 한 흐름에 들어옵니다.

처음부터 셀프호스팅으로 들어갈 필요는 없습니다. 먼저 Dub Cloud나 API로 작은 캠페인 하나를 연결해보세요. 링크 생성 규칙, UTM 규칙, 전환 이벤트 기준이 정리된 뒤에야 셀프호스팅 여부를 판단하는 편이 안전합니다.

개발팀이 직접 운영하려면 README보다 apps/web/.env.example, apps/web/docker-compose.yml, 공식 local development/self-hosting 문서를 먼저 보세요. 거기에 이 도구의 실제 운영 난이도가 거의 다 드러납니다.

참고자료

AI/IT도구에서 이어서 보면 좋은 글

한 번 더 클릭하게 만드는 내부 링크 구간입니다. 같은 주제의 실용 글로 이동시키고, 카테고리 허브로도 연결합니다.