A short link is a small thing, but it sits between you and your audience. When you print a QR code on a poster or put a link in a campaign email, the shortener decides where people land, how long the link lives, and who gets to see the click data. With a hosted service, that is a third party. The link is on their domain, the statistics are in their dashboard, and the link works for as long as their product and your plan allow.
Running your own shortener solves this, but many self-hosted options ask for a database server, a cache and a separate frontend build before the first redirect works.
shortlink is a self-hosted URL shortener in one binary. It stores everything in SQLite, supports custom slugs and expiry, draws QR codes, records click analytics per day, referrer, browser and device, and has an admin UI embedded in the binary. There is no JavaScript framework, no external service and no cgo. IP addresses are never stored.
The README says who it is for: clubs, small businesses, conference organisers and developers who want short links on their own domain, for posters, campaigns or docs, and who would rather not hand click data to a third party.
What it does
Slugs. If you do not choose a slug, you get a random one: 6 characters from an alphabet without look-alikes (0/O, 1/l/I), generated with crypto/rand and retried on collision. That matters on paper, where someone types the link by hand. Custom slugs are case-insensitive (COLLATE NOCASE), so Agenda and agenda are the same link, and they cannot shadow app routes such as admin or api.
Expiry. A link can expire. The expires field accepts a duration (72h, 30d), a date (2026-12-31) or an RFC 3339 timestamp. An unknown slug answers 404, and an expired one answers 410.
Redirects that stay countable. Redirects are 302 with Cache-Control: no-store. The README explains the choice: a 301 would be cached by browsers forever, so later clicks would go uncounted, and expiry or deletion would be ignored.
Analytics without IP addresses. Each click stores the time, the UTC day, the referrer host (not the full URL), and a coarse browser and device classification of the User-Agent. Bots such as link-preview fetchers are labelled bot. The click insert and the counter update share one transaction. Stats fill in empty days, so the per-day chart has no gaps.
QR codes. Every link has a QR code as a PNG, from 64 to 1024 pixels, at /admin/links/{slug}/qr.png?size=256.
Admin UI. Server-rendered templates embedded in the binary, with a CSS bar chart and the QR code inline. Because Basic-auth credentials are sent on cross-site requests too, state-changing admin requests go through Go's http.CrossOriginProtection (Fetch metadata and Origin checks) against CSRF.
Storage. modernc.org/sqlite, a pure-Go driver, in WAL mode, with foreign keys and cascade delete. Deleting a link deletes its clicks. QR codes come from github.com/skip2/go-qrcode.
How to use it
Install with Go:
go install github.com/AbdeldjalilChougui/shortlink/cmd/shortlink@latest
The README also lists prebuilt binaries for Linux, macOS and Windows (amd64 and arm64) on the GitHub releases page, with a checksums.txt file of SHA-256 sums. Or build from a checkout and start the server:
go build -o shortlink ./cmd/shortlink
SHORTLINK_TOKEN=change-me ./shortlink -addr :8080 -db shortlink.db -base-url https://s.example.com
SHORTLINK_TOKEN is the single admin token. -db is the SQLite file, and -base-url is the public address used to build short URLs. Open http://localhost:8080/admin and log in with Basic auth: any user name, the token as password.
Everything the UI does is also available over the API:
curl -H "Authorization: Bearer change-me" -d '{"url":"https://example.com/2026/agenda","slug":"agenda","expires":"30d"}' \
http://localhost:8080/api/links
# {"slug":"agenda","short_url":"https://s.example.com/agenda","url":"https://example.com/2026/agenda",...}
curl -I http://localhost:8080/agenda # 302 → destination
curl -H "Authorization: Bearer change-me" 'http://localhost:8080/api/links/agenda?days=30' # stats
The full route list is short:
| method | path | what it does |
|---|---|---|
| GET | /{slug} |
302 redirect (404 unknown, 410 expired) |
| POST | /api/links |
create: {"url", "slug"?, "expires"?}
|
| GET | /api/links |
list |
| GET | /api/links/{slug}?days=30 |
link and stats |
| DELETE | /api/links/{slug} |
delete the link and its clicks |
| GET |
/admin, /admin/links/{slug}
|
UI |
| GET | /admin/links/{slug}/qr.png?size=256 |
QR code PNG |
Things to know
- A single admin token. There are no user accounts and no per-user link lists. Everyone who has the token sees and manages every link.
- Links cannot be edited. To change a destination, delete the link and recreate it. Deleting also removes its click history.
- Days are bucketed in UTC. A click late in the evening in your timezone may land on the next day in the chart.
- The User-Agent classification is coarse. Bots that pretend to be browsers are counted as browsers, so treat click counts as an estimate.
- No rate limiting. Neither redirects nor the API are rate limited. If the service is exposed to abuse, put it behind a proxy.
-
What was tested.
go test -race ./...covers random and custom slugs (collisions, case-insensitive duplicates, reserved names), expiry with the 410 answer, the redirect headers, click recording with referrer and User-Agent, per-day stats with zero-filled days and a 7-day window, cascade delete, auth for the UI and the API, CSRF rejection of a cross-site form post, form validation errors, the QR PNG size, expiry parsing, and a User-Agent table.
Why I built it
The use case in the README is modest: a club, a small business or a conference that wants s.example.com/agenda on a poster. For that, the usual choice is between a hosted service, which keeps the click data and controls the link's lifetime, and a self-hosted stack that is larger than the problem.
I wanted the smallest thing that does the job properly. One binary and one SQLite file can be copied to a small server and backed up by copying a file. Building without cgo keeps cross-compilation simple. Server-rendered templates mean the admin UI has no build step and nothing to keep up to date on the frontend.
Privacy shaped the analytics. A poster campaign needs to know how many people scanned the code, on which day, and roughly from what kind of device. It does not need to know who they were. So the click record keeps the referrer host and a coarse device class, and never the IP address.
The details that look minor are the ones that decide whether a shortener is trustworthy: a 302 so that expiry and deletion really take effect, an alphabet without look-alike characters for links typed from paper, and reserved names so that a custom slug cannot hide the admin page.
Get the code
The source, the embedded admin UI and the tests are on GitHub: https://github.com/AbdeldjalilChougui/shortlink. It is MIT licensed. Issues and pull requests are welcome.
Originally published at abdeldjalilchougui.biz.
Top comments (0)