Self-host LinkBreeze: a Linktree alternative
Run LinkBreeze on a VPS with Docker Compose and Caddy: pinned image tags, cookieless click tracking, and the one volume that holds your whole site.
What LinkBreeze is
LinkBreeze is a self-hosted Linktree alternative: one Docker container that serves a public link-in-bio page and an admin dashboard, with its database in a single SQLite file. It is MIT licensed, written in TypeScript on Next.js, and published as a container image on Docker Hub as omnirise/linkbreeze and on GHCR as ghcr.io/omnirise/linkbreeze; older releases used ghcr.io/manak-hash/linkbreeze. To run it you need a VPS, a domain with an A record pointing at that VPS, ports 80 and 443 open, and Docker Engine with the Compose plugin.
This guide covers the deployment the repository actually supports: Docker Compose behind a reverse proxy that fetches its own certificates. It also covers what breaks, because a link in a bio is a public URL other people click, and a broken one costs you the click.
Before any of that, be clear about how new this project is.
Is LinkBreeze mature enough for a public profile link?
The first tagged release, v1.0.0, is dated 1 July 2026. This is a project a few months old, not a few years old.
The changelog mentions GitHub account visibility issues. On 2 November 2026 the canonical GitHub repository at github.com/OmniRise/LinkBreeze is public, alongside the project's official GitLab mirror, gitlab.com/omnirise00/linkbreeze, with the image on Docker Hub.
The data behind this chart
[
{
"week": "2026-06-29",
"releases": 3,
"cumulative": 3
},
{
"week": "2026-07-06",
"releases": 3,
"cumulative": 6
},
{
"week": "2026-07-13",
"releases": 1,
"cumulative": 7
},
{
"week": "2026-07-20",
"releases": 2,
"cumulative": 9
},
{
"week": "2026-07-27",
"releases": 3,
"cumulative": 12
},
{
"week": "2026-08-03",
"releases": 2,
"cumulative": 14
},
{
"week": "2026-08-10",
"releases": 4,
"cumulative": 18
},
{
"week": "2026-08-17",
"releases": 1,
"cumulative": 19
},
{
"week": "2026-08-24",
"releases": 1,
"cumulative": 20
},
{
"week": "2026-08-31",
"releases": 0,
"cumulative": 20
},
{
"week": "2026-09-07",
"releases": 0,
"cumulative": 20
},
{
"week": "2026-09-14",
"releases": 1,
"cumulative": 21
},
{
"week": "2026-09-21",
"releases": 1,
"cumulative": 22
}
]Since v1.0.0 the project has shipped 22 tagged releases across 13 calendar weeks, up to v1.4.1 on 23 September 2026. That chart ends at v1.4.1; v1.5.0 followed on 24 October and v1.5.1 on 27 October 2026.
Read that as two separate facts. The maintainer is active and bugs get fixed within days. The schema and the defaults are also still moving, so an instance you deploy and forget will drift a long way from the code being written.
The license protects you from the worst case. MIT plus a container image plus a SQLite file on your own disk means that if development stops, what you have keeps running. What it does not protect you from is a public-facing web app that stops receiving security fixes, which becomes a liability over time. Deploy this as something you will keep updating, and keep the backup routine below working from day one.
Pin the image tag, and do not run latest
The current release workflow pushes two tags per version, to Docker Hub and to GHCR: latest, and the git tag exactly as it was pushed, leading v included. The pinned tag for release v1.4.1 is therefore docker.io/omnirise/linkbreeze:v1.4.1. Releases before v1.4.0 were tagged differently: the workflow stripped the v, and those releases exist only on GHCR as bare numbers such as ghcr.io/manak-hash/linkbreeze:1.2.7. Write a tag in the wrong form for its release and Docker reports manifest unknown, because that tag was never pushed. Docker Hub, which the README now uses as its default pull path, also carries v1.5.1, the tag specified by the project's official Unraid package.
Pin it because latest moves. At the cadence in the chart above, a docker compose pull against latest is an unreviewed upgrade of a page your audience is using. With a pinned tag, an upgrade happens when you edit the file.
One more thing about the image. Since v1.4.0 it is a multi-arch manifest list for linux/amd64 and linux/arm64, each built on a native runner. If you run an ARM VPS rather than x86, the same tag pulls the arm64 build and nothing needs compiling on the box. Releases up to v1.3.2 were published for linux/amd64 only, and 32-bit arm/v7 boards are left out on purpose, so an older pin or a 32-bit board still fails with a no matching manifest error.
Deploy LinkBreeze behind Caddy with automatic TLS
Caddy requests and renews certificates from Let's Encrypt on its own, so TLS (transport layer security) needs no separate certificate step. The whole deployment is three files in one directory.
Generate the secret first:
mkdir -p ~/linkbreeze && cd ~/linkbreeze
printf 'SECRET_KEY=%s\n' "$(openssl rand -hex 32)" > .env
chmod 600 .envSECRET_KEY signs the admin session cookie and salts the analytics visitor hash, and since v1.4.0 it also derives the key that encrypts stored two-factor (TOTP) secrets. The compose file published with v1.4.1 defaults it to ${SECRET_KEY:-changeme-in-production}, so an instance using that file without setting the secret runs with a session signing key that is printed in the project's public repository. Set it before the first start, because changing it later logs you out and resets the analytics salt.
Write docker-compose.yml:
services:
linkbreeze:
image: docker.io/omnirise/linkbreeze:v1.4.1
restart: unless-stopped
volumes:
- linkbreeze-data:/app/data
environment:
- DATABASE_PATH=/app/data/linkbreeze.db
- SECRET_KEY=${SECRET_KEY}
- BASE_URL=https://links.example.com
networks:
- linkbreeze-net
caddy:
image: caddy:2-alpine
restart: unless-stopped
ports:
- "80:80"
- "443:443"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- caddy-data:/data
- caddy-config:/config
networks:
- linkbreeze-net
networks:
linkbreeze-net:
volumes:
linkbreeze-data:
caddy-data:
caddy-config:BASE_URL is optional and worth setting: it tells the app its real public address, so a request arriving with a forged Host header cannot make the app generate links to somebody else's domain.
Write Caddyfile next to it, with your own domain:
links.example.com {
encode zstd gzip
reverse_proxy linkbreeze:3000
}Caddy sets X-Forwarded-For and X-Forwarded-Proto on proxied requests by default, which supply the client address for analytics and the transport for session-cookie security. Bring it up:
docker compose up -d
docker compose ps
docker compose logs -f caddydocker compose ps should show the LinkBreeze container as healthy. The image ships its own healthcheck, wget --spider -q http://127.0.0.1:3000/api/health, so you do not need to add one. Do not copy the healthcheck out of the repository's own Caddy example: it calls curl, and the image is built on node:22-alpine, which carries busybox wget and no curl. That container reports unhealthy while serving pages perfectly well.
Open https://links.example.com in a browser. The first visit lands on the setup wizard at /setup, which creates the single admin account. After that the dashboard is at /dashboard and the login form at /login. In the pinned v1.4.1 release that account is local to this instance and there is no single sign-on hook, so if you want the dashboard protected by the same login as everything else you host, that has to come from a forward auth proxy in front of it such as a self-hosted Authentik. Native OIDC single sign-on is listed under Unreleased as of 2 November 2026.
Notice what the compose file does not do: it never publishes port 3000. Only Caddy listens on the public interface. If Compose file syntax is new, the Docker Compose basics for a VPS covers the parts this file assumes, and if you already run something else in front, Nginx, Caddy and Traefik compared explains what changes. The repository ships working examples for Nginx with Certbot, Traefik and a Cloudflare tunnel.
Where your data lives, and what a backup has to contain
DATABASE_PATH points at /app/data/linkbreeze.db. Uploaded avatars and link thumbnails are written beside it in /app/data/uploads. Both live in the named volume linkbreeze-data, so the unit of backup is the volume, not the database file on its own. Restore the file without the uploads directory and every image on the page returns a 404.
Everything else really is in that one database: pages, links, settings, theme, email subscribers and analytics rows.
Take the copy with the container stopped:
docker compose stop linkbreeze
docker compose cp linkbreeze:/app/data ./backup-$(date +%F)
docker compose start linkbreezeStop first because copying a SQLite database while a process is writing to it can capture a half-finished transaction, and the copy then opens as a corrupt file. The page is offline while the copy runs. Restoring is the same move in reverse:
docker compose stop linkbreeze
docker compose cp ./backup-2026-08-14/. linkbreeze:/app/data
docker compose start linkbreeze
docker compose logs -f linkbreezeThe dashboard also offers a JSON export, served from /api/backup as linkbreeze-backup-YYYY-MM-DD.json. It carries the profile, the links and their sections, the settings, the saved themes and the custom font entries. It does not carry analytics history, email subscribers, the admin account or uploaded files, and restoring it deletes the current rows in the six tables it does carry before inserting the file's. Treat it as a config snapshot for moving hosts or undoing an editing mistake. The volume copy is the backup.
Two storage rules apply here the same as anywhere else you are running SQLite in production on a VPS. Keep the database on local disk, because SQLite's locking is unreliable on a network filesystem and a corrupt page is how you find out. And if you swap the named volume for a host bind mount, chown the host directory first: the container runs as the non-root node user, uid 1000 in node:22-alpine, and a directory created by root is not writable by it, so the app cannot open the database and the container exits at startup. Bind mounts against named volumes in Compose covers that trade in full.
The analytics, and the consent banner you do not need
This is the feature that justifies self-hosting a page you could get free elsewhere.
The analytics are cookieless. The built-in analytics set no visitor cookie and load no third-party tracking script; external analytics and embeds are optional features. A visitor is identified by a SHA-256 hash of the IP address, the user agent string and a salt, truncated to 16 hexadecimal characters. The salt is itself a hash of the current UTC date and your SECRET_KEY, so it changes at midnight UTC and yesterday's hashes cannot be matched against today's. The raw IP address is never written to the database.
Clicks are counted on the server. Every http link on the public page points at /go/<id> on your own domain, which records the click and then answers with a 302 redirect to the real destination. Counting therefore works for readers with JavaScript disabled, and inside the in-app browsers that block background requests. Page views are recorded server-side when the public page renders; /api/track handles click and popup-open events.
Two exclusions are worth knowing. A request carrying a valid admin session is skipped, so editing your own page does not inflate the numbers. Known crawler user agents are skipped too.
On consent: the built-in analytics use no tracking cookie, but cookie rules also cover similar technologies, including device fingerprinting. Cookieless tracking alone does not establish that no consent banner is required. Your obligations still depend on where your readers live, so check them, along with any external analytics or embeds you enable.
One caveat that surprises people: rotate SECRET_KEY and the daily salt changes with it, so every returning visitor is counted as new from that moment.
Why is the analytics country column empty?
Because nothing in your stack sets a country header. LinkBreeze resolves the country from proxy headers such as cf-ipcountry and x-vercel-ip-country. On a VPS behind your own Caddy or Nginx, none of those headers exist, so the country is recorded as null and the breakdown stays blank. There is no GeoIP database inside the container.
Two ways to fill it. Put Cloudflare in front of the domain and enable its Add visitor location headers Managed Transform to supply cf-ipcountry. Or set one of those headers in your own reverse proxy from a local GeoIP lookup.
The related trap is worse, so check it. The click and view handlers read the client address from X-Forwarded-For first, then X-Real-IP, and fall back to 0.0.0.0 when neither header is present. Publish port 3000 straight to the internet with neither address header and visitors with the same user agent share a hash within each UTC day; different user agents still produce different hashes, and the hash rotates daily. The per-IP rate limits of 60 events per minute on /api/track and /go/<id> then each apply to your entire audience under the fallback address. Behind the reverse_proxy directive above, Caddy sets the header for you and both problems disappear.
Import from Linktree, and what does not come across
The migration wizard in the dashboard accepts a public profile URL or an exported file. It recognises linktr.ee, bento.me, lnk.bio, tap.link, hopp.bio, beacons.ai, solo.to, linkfly, mssg.me and LittleLink pages, plus generic HTML and JSON exports. For a Linktree or Bento URL it reads the __NEXT_DATA__ JSON those pages embed. For a static page it reads the anchor tags.
What comes across is the title, the URL, the description and the image of each link, whether the link is a social profile, and your display name, bio and avatar. You pick which of the found links to keep before anything is written to the database.
What does not come across is the analytics history, the theme and layout, email subscribers, scheduled publish dates, and anything the old platform keeps behind its own login. Plan on rebuilding the look by hand, and accept that the old click history stays on the old service.
The importer fetches the URL from your server rather than from your browser, so it refuses addresses that are not public. Private/local URLs are not allowed means you gave it an address inside your own network, and the refusal is deliberate: without it, anyone with dashboard access could use your server to probe machines that only your server can reach. The other messages you may see are Only http and https URLs are allowed, Request timed out and Response too large.
Scraping depends on somebody else's markup. In v1.5.1 the importer fixes a Linktree bug that pulled the platform's affiliate links instead of the profile's own links. Upgrade before importing from Linktree; profiles whose links are rendered only in the browser still need the File tab or manual entry. If the wizard finds nothing on a page that clearly has links, add the links by hand rather than waiting for a fix. If what you actually want is measurable short links rather than a profile page, a self-hosted URL shortener like Shlink does that job and runs happily on the same box.
Updating a pinned deployment
# edit the image tag in docker-compose.yml, then
docker compose pull
docker compose up -d
docker compose logs -f linkbreezeSchema migrations run automatically when the container starts. There is no documented way to run them backwards, so take the volume copy first. An upgrade you cannot reverse is only safe when you can restore what was there before it.
The dashboard is meant to show a banner when a newer release exists. The pinned v1.4.1 checks a small version file on GitHub; since v1.5.0, released on 24 October 2026, the banner's check fetches linkbreeze.omnirise.dev/latest-version.json. Results are cached for 24 hours, but the manual Check now button bypasses that cache, including in v1.4.1. These checks send no instance data in their request payload. The changelog says v1.2.0 to v1.4.0 polled an address that answered 404 and never showed the banner. Until you run a version with the website endpoint, do not wait for the banner: watch the changelog at linkbreeze.omnirise.dev/changelog yourself. In v1.5.1, Settings also has an update status card that checks GitHub and the website, with a Recheck button that bypasses the cache. Read the release notes before you move the tag, because at this stage of the project a minor version can change defaults you rely on.
Failure modes and the strings you will see
manifest unknown when pulling. The tag is written in the wrong form for its release. From v1.4.0 on, tags keep the v, so use :v1.4.1. GHCR releases up to v1.3.2 use bare numbers such as :1.2.7, and Docker Hub also carries newer version tags such as v1.5.1.
no matching manifest for linux/arm64/v8 in the manifest list entries. You pinned a release from before v1.4.0, which was published for amd64 only. Move the pin to v1.4.1, which carries an arm64 build. A 32-bit arm/v7 board gets the same kind of error on every release, because that platform is not built on purpose.
The container reports unhealthy while the page loads fine. A healthcheck in your compose file is calling curl, which the image does not contain. Delete it and let the image's own wget healthcheck run.
Caddy serves a certificate error, or nothing at all. Check docker compose logs caddy. Check that the A record points at this VPS and that ports 80 and 443 are reachable: Caddy can validate through an HTTP challenge on port 80 or a TLS-ALPN challenge on port 443.
Unique visitors is stuck at 1. Check whether the proxy sets X-Forwarded-For or X-Real-IP. Without either header, visitors with identical user agents share a hash within each UTC day; the hash also includes a daily salt, so missing headers do not make every visitor hash identically forever.
The container exits right after startup, having worked yesterday. If you moved from a named volume to a host bind mount, the data directory is owned by root and the app runs as uid 1000, so it cannot open the database file. sudo chown -R 1000:1000 the host directory.
Tracking requests answered with HTTP 429. The per-IP throttle on /api/track was hit. The separate throttle on /go/<id> skips recording the click but still returns the 302 redirect to the destination.
FAQ
Is LinkBreeze ready for a public link in bio?
It is a young project, and the first release is dated 1 July 2026. It shipped 22 tagged releases between then and v1.4.1 on 23 September 2026, most of them before mid-August, so behaviour has changed quickly. Releases v1.5.0 and v1.5.1 followed on 24 and 27 October 2026, and the canonical GitHub repository is public as of 2 November 2026. The MIT license and the local SQLite file mean you keep a working page even if development stops, but a public web app without security fixes turns into a liability, so treat this as software you will keep updating rather than install once.
Which LinkBreeze image tag should I run?
Run the version tag, for example docker.io/omnirise/linkbreeze:v1.4.1, and change it deliberately. Since v1.4.0 the release workflow pushes latest and the git tag with its leading v, so :1.4.1 without the v does not exist and Docker answers manifest unknown. Releases up to v1.3.2 are the reverse: bare numbers on GHCR only. The image is built for linux/amd64 and linux/arm64 since v1.4.0, so an arm64 VPS pulls it directly with no local build.
Why does the country breakdown stay empty in LinkBreeze analytics?
LinkBreeze reads the visitor country from proxy headers such as cf-ipcountry or x-vercel-ip-country, and it carries no GeoIP database of its own. A VPS behind your own Caddy or Nginx sets none of those headers, so the country is stored as null. Put Cloudflare in front of the domain and enable its Add visitor location headers Managed Transform, or have your reverse proxy set one of those headers from a local GeoIP lookup.
What exactly do I back up, and how do I restore it?
Back up the whole linkbreeze-data volume, not just the database file. /app/data/linkbreeze.db holds every link, page, setting, subscriber and analytics row, and /app/data/uploads holds the avatar and thumbnail images that the page references. Stop the container, run docker compose cp linkbreeze:/app/data ./backup-$(date +%F), then start it again. Restore by copying the directory back into the stopped container and starting it. The JSON export from the dashboard is a config snapshot of profile, links, settings, themes and font entries, and it contains no analytics and no images.
Does importing from Linktree bring my analytics and theme with it?
No. The migration wizard reads the link titles, URLs, descriptions and images from your old public profile, plus your display name, bio and avatar. Analytics history, the theme, email subscribers and scheduled publish dates stay behind. Rebuild the look in the theme editor after the import, and expect your click history to remain on the old platform.