How to self-host LinkBreeze with Docker Compose
Run LinkBreeze for your own link-in-bio page with Docker Compose and Caddy. Pin image tags, enable cookieless click tracking, and back up one SQLite volume.
Wetín LinkBreeze be
LinkBreeze na self-hosted alternative to Linktree: na one Docker container wey dey serve public link-in-bio page and admin dashboard, while e keep database for one SQLite file. MIT license cover am, dem write am for TypeScript on Next.js, and dem publish am as container image for Docker Hub as omnirise/linkbreeze and for GHCR as ghcr.io/omnirise/linkbreeze; older releases use ghcr.io/manak-hash/linkbreeze. To run am, you need VPS, domain wey get A record pointing to that VPS, open ports 80 and 443, plus Docker Engine with Compose plugin.
This guide cover the deployment wey the repository really support: Docker Compose behind reverse proxy wey dey fetch its own certificates. E also cover wetin fit break, because link for bio na public URL wey other people go click, and broken link fit make you lose that click.
Before all that one, make you understand say this project still new well-well.
LinkBreeze don mature reach public profile link?
The first tagged release, v1.0.0, get date of 1 July 2026. This project na only few months old, no be project wey don dey for years.
The changelog mention GitHub account visibility problems. On 2 November 2026, the canonical GitHub repository for github.com/OmniRise/LinkBreeze dey public, together with the project official GitLab mirror, gitlab.com/omnirise00/linkbreeze, and the image for Docker Hub.
Di data wey dey behind dis 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 don release 22 tagged releases across 13 calendar weeks, reach v1.4.1 on 23 September 2026. That chart end for v1.4.1; v1.5.0 follow on 24 October, and v1.5.1 follow on 27 October 2026.
Treat dem as two separate facts. The maintainer dey active, and dem dey fix bugs within days. But the schema and defaults still dey change, so instance wey you deploy and forget go drift far from the code wey dem dey write.
The license protect you from the worst case. MIT, together with a container image and a SQLite file for your own disk, mean say if development stop, wetin you get go continue to run. But e no protect you from public-facing web app wey stop receiving security fixes; over time, that one fit become liability. Deploy this as something wey you go keep updating, and make the backup routine below dey work from day one.
Pin image tag, and no run latest
The current release workflow dey push two tags for each version, to Docker Hub and GHCR: latest, plus the git tag exactly as dem push am, including v. So, the pinned tag for release v1.4.1 na docker.io/omnirise/linkbreeze:v1.4.1. Releases before v1.4.0 get tagged another way: the workflow remove v, and those releases dey only for GHCR as bare numbers like ghcr.io/manak-hash/linkbreeze:1.2.7. If you write tag for wrong format for the release, Docker report manifest unknown, because dem never push that tag. Docker Hub, wey README now use as the default pull path, also get v1.5.1, the tag wey the project official Unraid package specify.
Pin am because latest dey change. With the schedule for the chart above, docker compose pull against latest na upgrade wey nobody review for page wey your audience dey use. With pinned tag, upgrade go happen only when you edit the file.
One more thing about the image. Since v1.4.0, e be multi-arch manifest list for linux/amd64 and linux/arm64, and dem build each one on native runner. If you run ARM VPS instead of x86, the same tag go pull the arm64 build, and nothing need compile for the machine. Releases up to v1.3.2 na linux/amd64 only, and dem intentionally leave out 32-bit arm/v7 boards, so older pin or 32-bit board still fail with no matching manifest error.
Deploy LinkBreeze behind Caddy with automatic TLS
Caddy dey request and renew certificates from Let's Encrypt by itself, so TLS (transport layer security) no need separate certificate step. The whole deployment na three files for 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 dey sign the admin session cookie and add salt to the analytics visitor hash. Since v1.4.0, e also dey derive the key wey dey encrypt stored two-factor (TOTP) secrets. The compose file wey dem publish with v1.4.1 set am to ${SECRET_KEY:-changeme-in-production} by default. So, instance wey use that file without setting the secret go run with session signing key wey dem print for the project's public repository. Set am before the first start, because if you change am later, e go log you out and reset 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 optional, but e good make you set am. E tells the app the real public address, so request wey arrive with forged Host header no fit make the app generate links to another person's domain.
Write Caddyfile beside am, with your own domain:
links.example.com {
encode zstd gzip
reverse_proxy linkbreeze:3000
}Caddy dey set X-Forwarded-For and X-Forwarded-Proto for proxied requests by default. Dem dey provide the client address for analytics and the transport information wey session-cookie security need. Bring am up:
docker compose up -d
docker compose ps
docker compose logs -f caddydocker compose ps suppose show the LinkBreeze container as healthy. The image get its own healthcheck, wget --spider -q http://127.0.0.1:3000/api/health, so you no need add another one. No copy the healthcheck from the repository's own Caddy example. E dey call curl, but the image dey built on node:22-alpine, wey get busybox wget and no curl. That container dey report unhealthy even when e dey serve pages well.
Open https://links.example.com for browser. The first visit go land for setup wizard at /setup, wey dey create the only admin account. After that, dashboard dey at /dashboard and login form dey at /login. For the pinned v1.4.1 release, that account dey local to this instance and no single sign-on hook dey available. So if you want protect the dashboard with the same login wey you use for other things you host, you need put a forward auth proxy in front of am, such as self-hosted Authentik. Native OIDC single sign-on dey listed under Unreleased as of 2 November 2026.
Notice wetin the compose file no do: e no publish port 3000 at all. Na only Caddy dey listen on the public interface. If Compose file syntax still new to you, Docker Compose basics for a VPS dey explain the parts wey this file assume. If you already get another service for front, Nginx, Caddy and Traefik compared dey explain wetin go change. The repository get working examples for Nginx with Certbot, Traefik and a Cloudflare tunnel.
Wia your data dey, and wetin backup suppose contain
DATABASE_PATH dey point to /app/data/linkbreeze.db. Dem dey write uploaded avatars and link thumbnails beside am for /app/data/uploads. Both dey inside the named volume linkbreeze-data, so na the volume be the backup unit, no be the database file by itself. If you restore the file without the uploads directory, every image for the page go return 404.
Everything else really dey inside that one database: pages, links, settings, theme, email subscribers and analytics rows.
Take the copy when the container don stop:
docker compose stop linkbreeze
docker compose cp linkbreeze:/app/data ./backup-$(date +%F)
docker compose start linkbreezeStop am first because if process dey write to SQLite database while you dey copy am, the copy fit capture transaction wey never finish, and the copy go then open as corrupt file. The page go dey offline while the copy dey run. To restore am, na the same step for 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 still get JSON export, wey dem dey serve from /api/backup as linkbreeze-backup-YYYY-MM-DD.json. E carry the profile, the links and their sections, the settings, the saved themes and the custom font entries. E no carry analytics history, email subscribers, the admin account or uploaded files. When you restore am, e delete the current rows for the six tables wey e carry before e insert the rows from the file. Treat am as config snapshot for moving hosts or undoing editing mistake. Na the volume copy be the backup.
Two storage rules apply here just like anywhere else wey you dey run SQLite for production on a VPS. Keep the database for local disk, because SQLite locking no reliable for network filesystem, and na corrupt page go show you the problem. If you replace the named volume with host bind mount, chown the host directory first: the container dey run as the non-root node user, uid 1000 for node:22-alpine, and directory wey root create no writable for am. Because of that, the app no fit open the database and the container go exit during startup. Bind mounts against named volumes for Compose explain that trade fully.
Analytics, plus consent banner wey you no need
Na this feature dey justify self-hosting one page wey you fit get free for another place.
The analytics no use cookies. The built-in analytics no set visitor cookie and no load any third-party tracking script; external analytics and embeds na optional features. System identify visitor with SHA-256 hash of the IP address, user agent string, and one salt, then truncate am to 16 hexadecimal characters. The salt itself na hash of the current UTC date and your SECRET_KEY, so e dey change for midnight UTC and yesterday hashes no fit match today own. The raw IP address no dey ever write to the database.
Server dey count clicks. Every http link for the public page dey point to /go/<id> for your own domain. E record the click, then answer with 302 redirect go the real destination. Because of this, counting still work for readers wey disable JavaScript and inside in-app browsers wey block background requests. Server dey record page views when the public page render; /api/track dey handle click and popup-open events.
Two exclusions dey important. Request wey carry valid admin session dey skip, so editing your own page no dey increase the numbers. Known crawler user agents dey skip too.
About consent: the built-in analytics no use tracking cookie, but cookie rules also cover similar technologies, including device fingerprinting. Cookieless tracking by itself no prove say consent banner no dey required. Your obligations still depend on where your readers dey, so check dem, together with any external analytics or embeds wey you enable.
One caveat wey fit surprise people: if you rotate SECRET_KEY, the daily salt go change too, so every returning visitor go count as new from that moment.
Why analytics country column empty?
Because nothing for your stack dey set country header. LinkBreeze dey resolve country from proxy headers like cf-ipcountry and x-vercel-ip-country. If your VPS dey behind your own Caddy or Nginx, none of those headers dey exist, so system record the country as null and the breakdown remain blank. No GeoIP database dey inside the container.
You get two ways to fill am. Put Cloudflare in front of the domain and enable the Add visitor location headers Managed Transform, so e go supply cf-ipcountry. Or set one of those headers for your own reverse proxy from local GeoIP lookup.
The related trap worse, so check am. The click and view handlers first read client address from X-Forwarded-For, then X-Real-IP, and use 0.0.0.0 when none of the headers dey present. If you publish port 3000 straight to internet without any address header, visitors wey get the same user agent go share one hash inside each UTC day; different user agents still go produce different hashes, and the hash go change every day. The per-IP rate limits of 60 events per minute for /api/track and /go/<id> go then apply separately to your entire audience under the fallback address. Behind the reverse_proxy directive wey dey above, Caddy go set the header for you, and both problems go disappear.
Wetin Import from Linktree Carry Come, and Wetin No Go Come
The migration wizard for dashboard dey accept public profile URL or exported file. E recognise 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 Linktree or Bento URL, e dey read the __NEXT_DATA__ JSON wey those pages embed. For static page, e dey read the anchor tags.
The things wey go come na title, URL, description and image of each link, whether the link na social profile, plus your display name, bio and avatar. You go choose which links among the ones e find you wan keep before e write anything to database.
The things wey no go come na analytics history, theme and layout, email subscribers, scheduled publish dates, and anything wey the old platform keep behind im own login. Plan to rebuild the appearance by hand, and accept say old click history go remain for the old service.
The importer dey fetch the URL from your server, no be from your browser, so e dey reject addresses wey no public. Private/local URLs are not allowed mean say you give am address inside your own network, and the refusal na deliberate: without am, anybody wey get dashboard access fit use your server probe machines wey only your server fit reach. The other messages wey you fit see na Only http and https URLs are allowed, Request timed out and Response too large.
Scraping depend on another person markup. For v1.5.1, the importer fix one Linktree bug wey dey pull the platform affiliate links instead of the profile own links. Upgrade before you import from Linktree; profiles wey dem render their links only inside browser still need the File tab or manual entry. If wizard no find anything for page wey clearly get links, add the links by hand instead of waiting for fix. If wetin you really want na measurable short links instead of profile page, self-hosted URL shortener like Shlink fit do the work and e fit run well for the same box.
Update deployment wey you pin
# edit the image tag in docker-compose.yml, then
docker compose pull
docker compose up -d
docker compose logs -f linkbreezeSchema migrations dey run automatically when container start. No documented way dey to run dem backwards, so first make copy of the volume. Upgrade wey you no fit reverse safe only when you fit restore wetin dey there before.
Dashboard suppose show banner when newer release dey. The pinned v1.4.1 dey check small version file for GitHub; since v1.5.0, wey release on 24 October 2026, the banner check dey fetch linkbreeze.omnirise.dev/latest-version.json. Results dey cache for 24 hours, but manual Check now button dey bypass that cache, including for v1.4.1. These checks no send any instance data inside request payload. Changelog talk say v1.2.0 to v1.4.0 poll address wey answer 404 and never show the banner. Until you run version wey get the website endpoint, no wait for the banner: monitor the changelog for linkbreeze.omnirise.dev/changelog by yourself. For v1.5.1, Settings also get update status card wey dey check GitHub and the website, with Recheck button wey dey bypass the cache. Read release notes before you move the tag, because for this stage of the project, minor version fit change defaults wey you dey rely on.
Failure modes and strings wey you go see
manifest unknown when e dey pull. You write the tag for wrong format for that release. From v1.4.0, tags dey keep v, so use :v1.4.1. GHCR releases up to v1.3.2 use bare numbers like :1.2.7, and Docker Hub still get newer version tags like v1.5.1.
no matching manifest for linux/arm64/v8 in the manifest list entries. You pin release wey come before v1.4.0, and dem publish am for amd64 only. Move the pin go v1.4.1, wey get arm64 build. A 32-bit arm/v7 board go get the same kind error for every release, because dem no build for that platform on purpose.
The container dey report unhealthy while the page dey load well. A healthcheck for your compose file dey call curl, but the image no contain am. Delete am and allow the image own wget healthcheck run.
Caddy dey serve certificate error, or e no dey serve anything. Check docker compose logs caddy. Confirm say the A record dey point to this VPS and ports 80 and 443 dey reachable. Caddy fit validate through HTTP challenge for port 80 or TLS-ALPN challenge for port 443.
Unique visitors remain for 1. Check whether the proxy dey set X-Forwarded-For or X-Real-IP. If both headers no dey, visitors wey get the same user agent go share one hash inside each UTC day. The hash also include daily salt, so missing headers no mean say every visitor go keep the same hash forever.
The container dey exit immediately after startup, even though e work yesterday. If you move from named volume to host bind mount, root own the data directory and the app dey run as uid 1000, so e no fit open the database file. sudo chown -R 1000:1000 the host directory.
Tracking requests dey return HTTP 429. The per-IP throttle for /api/track don reach its limit. The separate throttle for /go/<id> no record the click, but e still return the 302 redirect to the destination.
FAQ
LinkBreeze ready to use for public link in bio?
Na young project, and e first release come out on 1 July 2026. E release 22 tagged releases between then and v1.4.1 on 23 September 2026, and most of dem come out before mid-August, so behaviour change quickly. Releases v1.5.0 and v1.5.1 follow on 24 and 27 October 2026, and canonical GitHub repository become public as of 2 November 2026. MIT license and local SQLite file mean say you still get working page even if development stop. But public web app without security fixes fit become liability, so treat am as software wey you go keep updating, not something wey you install once.
Which LinkBreeze image tag I suppose run?
Run the version tag, for example docker.io/omnirise/linkbreeze:v1.4.1, and change am deliberately. Since v1.4.0, release workflow dey push latest and git tag with the leading v, so :1.4.1 without v no dey exist and Docker answer manifest unknown. Releases up to v1.3.2 be the opposite: na bare numbers dey for GHCR only. The image build for linux/amd64 and linux/arm64 since v1.4.0, so arm64 VPS fit pull am directly without local build.
Why country breakdown for LinkBreeze analytics remain empty?
LinkBreeze dey read visitor country from proxy headers like cf-ipcountry or x-vercel-ip-country, and e no get GeoIP database of its own. VPS wey dey behind your own Caddy or Nginx no dey set any of those headers, so system store country as null. Put Cloudflare in front of the domain and enable Add visitor location headers Managed Transform, or make your reverse proxy set one of those headers from local GeoIP lookup.
Wetin exactly I suppose back up, and how I go restore am?
Back up the whole linkbreeze-data volume, no be only the database file. /app/data/linkbreeze.db hold every link, page, setting, subscriber and analytics row, while /app/data/uploads hold avatar and thumbnail images wey the page dey reference. Stop the container, run docker compose cp linkbreeze:/app/data ./backup-$(date +%F), then start am again. To restore, copy the directory back into the stopped container and start am. JSON export from dashboard na config snapshot of profile, links, settings, themes and font entries. E no contain analytics or images.
Import from Linktree go carry my analytics and theme come?
No. Migration wizard dey read link titles, URLs, descriptions and images from your old public profile, together with display name, bio and avatar. Analytics history, theme, email subscribers and scheduled publish dates remain for the old platform. Rebuild the look inside theme editor after the import, and expect say your click history go remain for the old platform.