Build Dub

YESreplaces $90/mosaves $1,080/yrback to the verdict

0%0 of 18 items done

Saved on this device only. Tick prerequisites first, then work the phases in order · do not start one until the checks above it pass.

A link shortener on your own domain with click analytics: CSPRNG slugs, a redirect that never waits on the database, clicks with country, referrer and device but no raw IP, a private admin with per-link stats, a token API, and QR codes. Dub itself is open source; this is the 200-line version for one person and a domain you will keep forever.

estimated effort one sittingthe files for this build are in the project pack

RuntimeNode 22, node:http and node:sqliteHostingA VPS behind Caddy on a domain you will keep

Before step 1

Everything below is assumed from the first step. Tick each one when you actually have it, not when you plan to.

installfree
Why Everything in this build runs on it: the server, the scripts, the tests.
Get it Download the LTS installer from nodejs.org, or install with your package manager (brew install node, or nvm install 22). Restart the terminal afterwards. open ↗
Verify node --version prints v22 or higher
installfree
Why Every step below is a command you type or a file you edit.
Get it VS Code (code.visualstudio.com), Cursor or Zed. Open a folder for the project and use the editor's built-in terminal. open ↗
Verify You can open a folder and run a command in its terminal
installfree
Why History for your code, and the way most hosts deploy.
Get it Install from git-scm.com or with your package manager, then run git init in the project folder once it exists. open ↗
Verify git --version prints a version
accountroughly $10 to $30 a year
Why Every link you share depends on it. Auto-renew on.
Get it A short .co, .link or .to at Porkbun or Cloudflare Registrar; turn on auto-renew. open ↗
decidefree
Why Click rows store hashes.
Get it openssl rand -hex 32.
decidefree
Why Phase 4 exposes a token-protected API.
Get it openssl rand -base64 32 into .env as API_TOKEN.
accountabout $5 a month
Why This needs one process running all the time with a public address.
Get it Hetzner Cloud (from about 4 EUR), DigitalOcean or Fly.io. Ubuntu 24.04, the smallest size. You need SSH access and a public IP. Only needed for the deploy phase; develop locally first. open ↗
installfree
Why Automatic HTTPS in front of the Node process. Without TLS the browser features this relies on (and your visitors' trust) do not work.
Get it On the VPS: follow the install steps at caddyserver.com/docs/install for Ubuntu. One Caddyfile with your domain and a reverse_proxy line is the whole config. open ↗
Verify caddy version prints a version on the server

Data model

Create these before the first phase that stores anything. Changing a table later is the expensive kind of change.

- links: id, slug (unique, unambiguous alphabet), url, title, created_at, expires_at, active
- clicks: id, link_id, clicked_at, referer_host, country, device_class, ip_hash
Never store the raw IP or user agent; hash with a daily salt and bucket the device.

Environment variables

These go in a .env file the app reads at startup. The pack's .env.example is this table as a file · copy it, never commit the filled-in version.

Variable	Needed	Example	Where the value comes from
`PORT`	required	`3000`	Any free port.
`DATABASE_PATH`	required	`./data/links.db`	SQLite file.
`SITE_URL`	required	`https://yr.link`	The short domain.
`FALLBACK_URL`	required	`https://yourdomain.com`	Where unknown or inactive slugs land.
`IP_SALT`secret	required	`hex`	openssl rand -hex 32.
`API_TOKEN`secret	required	`base64`	openssl rand -base64 32.
`ADMIN_USER`	required	`admin`	Any username for the basic-auth admin pages.
`ADMIN_PASS`secret	required	`change-me-to-a-long-random-string`	Generate one: openssl rand -base64 24. Never reuse a real password.

The build, in order

1
Redirects
GET /:slug 302s; unknown slugs fall back; reserved paths cannot be slugs.
1. links (id, slug unique, url, title, created_at, expires_at, active), clicks (id, link_id, clicked_at, referer_host, country, device_class, ip_hash).
  terminal
  mkdir shortener && cd shortener && git init && npm init -y && npm pkg set type=module mkdir -p data && cp .env.example .env
done when · tick each as it passes
next phase
2
Click logging
After the redirect, never before; bots bucketed.
done when · tick each as it passes
next phase
3
Admin and analytics
Create, edit target without changing the slug, deactivate, expire; stats per link.
done when · tick each as it passes
next phase
4
API and QR
A token-protected POST for scripts and a QR image per link.
2. terminal
  npm install qrcode@1
done when · tick each as it passes
next phase
5
Deploy
HTTPS, service, backup, README.
2. Files README.md
done when · tick each as it passes
next phase
6
Operate it like a productproduct builder
Only for the product-builder path: know when the redirect is down, never lose the database, and keep the server patched.
1. Answer 200 with the build id and a quick database read. Point a free uptime monitor (or your own, from the Healthchecks entry on this site) at it so an outage is noticed before a user notices.
2. One JSON line per request: method, path, status, duration, no raw IPs. Rotate weekly with logrotate, keep eight.
3. SQLite's .backup command makes a consistent copy while the app runs. Copy it to object storage or a second machine; then, once, restore it into a fresh checkout and confirm the app reads it.
  terminal
  sqlite3 data/app.db ".backup '/tmp/app-$(date +%F).db'" rclone copy /tmp/app-$(date +%F).db remote:backups/
4. Firewall allowing only 22, 80 and 443; unattended security updates on; the app running as an unprivileged user under systemd with Restart=on-failure.
done when · tick each as it passes

what this build does not replace

Conversion tracking, partner payouts, workspaces: the $90 product.
partner and affiliate payouts
conversion tracking through to revenue
team workspaces and folders
the polished analytics dashboard and API

after v1, if you want it

UTM parameters appended per link
Bulk import from a CSV

Need the files? The project pack on the verdict page hands your agent the whole brief · more seo & marketing.