Cómo autoalojar LinkBreeze con Docker Compose
Despliega LinkBreeze en un VPS con Docker Compose y Caddy. Usa tags de imagen fijados, tracking sin cookies y un único volumen para todo el sitio.
Qué es LinkBreeze
LinkBreeze es una alternativa autoalojada a Linktree: un contenedor Docker que sirve una página pública de enlaces en la biografía y un panel de administración, con la base de datos en un único archivo SQLite. Tiene licencia MIT, está escrito en TypeScript sobre Next.js y se publica como imagen de contenedor en Docker Hub con el nombre omnirise/linkbreeze y en GHCR con el nombre ghcr.io/omnirise/linkbreeze; las versiones anteriores usaban ghcr.io/manak-hash/linkbreeze. Para ejecutarlo necesita un VPS, un dominio con un registro A que apunte a ese VPS, los puertos 80 y 443 abiertos y Docker Engine con el plugin Compose.
Esta guía cubre el despliegue que el repositorio admite realmente: Docker Compose detrás de un reverse proxy que obtiene sus propios certificados. También cubre los fallos habituales, porque un enlace en una biografía es una URL pública en la que otras personas hacen clic y, si deja de funcionar, se pierde ese clic.
Antes de continuar, tenga claro lo reciente que es este proyecto.
¿LinkBreeze tiene la madurez suficiente para un enlace de perfil público?
La primera versión etiquetada, v1.0.0, está fechada el 1 de julio de 2026. Este es un proyecto con unos pocos meses de antigüedad, no con varios años.
El registro de cambios menciona problemas de visibilidad de la cuenta de GitHub. El 2 de noviembre de 2026, el repositorio canónico de GitHub en github.com/OmniRise/LinkBreeze es público, junto con el mirror oficial del proyecto en GitLab, gitlab.com/omnirise00/linkbreeze, y la imagen en Docker Hub.
Los datos de este gráfico
[
{
"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
}
]Desde v1.0.0, el proyecto ha publicado 22 versiones etiquetadas en 13 semanas naturales, hasta v1.4.1 el 23 de septiembre de 2026. Ese gráfico termina en v1.4.1; v1.5.0 se publicó el 24 de octubre y v1.5.1 el 27 de octubre de 2026.
Interprete esto como dos hechos independientes. El mantenedor sigue activo y los errores se corrigen en cuestión de días. El esquema y los valores predeterminados también siguen cambiando, por lo que una instancia que despliegue y deje sin supervisión se alejará considerablemente del código que se está desarrollando.
La licencia le protege frente al peor caso. MIT, una imagen de contenedor y un archivo SQLite en su propio disco implican que, si el desarrollo se detiene, lo que ya tiene seguirá funcionando. Lo que la licencia no evita es que una aplicación web expuesta públicamente deje de recibir correcciones de seguridad y se convierta en un riesgo con el tiempo. Despliegue esto como un servicio que seguirá actualizando y mantenga operativa la rutina de copias de seguridad siguiente desde el primer día.
Fije la etiqueta de la imagen y no use latest
El flujo de publicación actual inserta dos etiquetas por versión, en Docker Hub y GHCR: latest y la etiqueta de Git exactamente como se insertó, incluido v. Por tanto, la etiqueta fijada para la versión v1.4.1 es docker.io/omnirise/linkbreeze:v1.4.1. Las versiones anteriores a v1.4.0 usaban otro formato: el flujo eliminaba v, y esas versiones sólo existen en GHCR como números sin prefijo, por ejemplo ghcr.io/manak-hash/linkbreeze:1.2.7. Si escribe una etiqueta con el formato incorrecto para su versión, Docker muestra manifest unknown porque esa etiqueta nunca se insertó. Docker Hub, que ahora usa el README como ruta de extracción predeterminada, también contiene v1.5.1, la etiqueta especificada por el paquete oficial de Unraid del proyecto.
Fije la etiqueta porque latest cambia. Con la frecuencia indicada en el gráfico anterior, un docker compose pull contra latest actualiza sin revisión una página que está usando su audiencia. Con una etiqueta fijada, la actualización se produce cuando edita el archivo.
Hay otro aspecto de la imagen. Desde v1.4.0, es una lista de manifiestos multi-arch para linux/amd64 y linux/arm64, cada uno compilado en un runner nativo. Si ejecuta un VPS ARM en lugar de x86, la misma etiqueta descarga la compilación arm64 y no es necesario compilar nada en el servidor. Las versiones hasta v1.3.2 se publicaron sólo para linux/amd64, y las placas de 32 bits arm/v7 se excluyen intencionadamente, por lo que una etiqueta fijada antigua o una placa de 32 bits todavía falla con un error no matching manifest.
Implementar LinkBreeze detrás de Caddy con TLS automático
Caddy solicita y renueva los certificados de Let's Encrypt por su cuenta, por lo que TLS (seguridad de la capa de transporte) no requiere un paso independiente para el certificado. Toda la implementación consta de tres archivos en un mismo directorio.
Genere primero el secreto:
mkdir -p ~/linkbreeze && cd ~/linkbreeze
printf 'SECRET_KEY=%s\n' "$(openssl rand -hex 32)" > .env
chmod 600 .envSECRET_KEY firma la cookie de sesión del administrador y añade salt a la función hash de los visitantes de analytics. Desde v1.4.0 también deriva la clave que cifra los secretos TOTP de dos factores almacenados. El archivo compose publicado con v1.4.1 lo establece de forma predeterminada en ${SECRET_KEY:-changeme-in-production}. Por tanto, una instancia que use ese archivo sin establecer el secreto se ejecuta con una clave de firma de sesión publicada en el repositorio público del proyecto. Establézcalo antes del primer arranque, porque cambiarlo más adelante cerrará su sesión y restablecerá el salt de analytics.
Escriba 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 es opcional, pero conviene establecerlo. Indica a la aplicación su dirección pública real. Así, una petición con una cabecera Host falsificada no puede hacer que la aplicación genere enlaces al dominio de otra persona.
Escriba Caddyfile junto a él, con su propio dominio:
links.example.com {
encode zstd gzip
reverse_proxy linkbreeze:3000
}Caddy establece X-Forwarded-For y X-Forwarded-Proto de forma predeterminada en las peticiones que pasan por el proxy. Estas cabeceras proporcionan la dirección del cliente para analytics y el protocolo de transporte para proteger la cookie de sesión. Inícielo:
docker compose up -d
docker compose ps
docker compose logs -f caddydocker compose ps debería mostrar el contenedor de LinkBreeze como healthy. La imagen incluye su propio healthcheck, wget --spider -q http://127.0.0.1:3000/api/health, por lo que no necesita añadir otro. No copie el healthcheck del ejemplo de Caddy del repositorio. Ejecuta curl, y la imagen está basada en node:22-alpine, que incluye busybox wget y no incluye curl. Ese contenedor informa unhealthy aunque sirve las páginas correctamente.
Abra https://links.example.com en un navegador. La primera visita llega al asistente de configuración en /setup, que crea la única cuenta de administrador. Después, el dashboard está en /dashboard y el formulario de inicio de sesión en /login. En la versión v1.4.1 fijada, esa cuenta es local a esta instancia y no existe ningún enlace de single sign-on. Por tanto, si quiere proteger el dashboard con el mismo inicio de sesión que usa para todo lo demás que aloja, debe hacerlo mediante un proxy de autenticación externa delante de este servicio, como Authentik autoalojado. El single sign-on nativo mediante OIDC aparece como Unreleased a fecha de 2 November 2026.
Observe lo que no hace el archivo compose: nunca publica el puerto 3000. Sólo Caddy escucha en la interfaz pública. Si la sintaxis de los archivos Compose es nueva para usted, los conceptos básicos de Docker Compose para un VPS cubren las partes que este archivo presupone. Si ya ejecuta otro servicio delante, comparación entre Nginx, Caddy y Traefik explica qué cambia. El repositorio incluye ejemplos funcionales para Nginx con Certbot, Traefik y un túnel de Cloudflare.
Dónde se almacenan los datos y qué debe contener una copia de seguridad
DATABASE_PATH apunta a /app/data/linkbreeze.db. Los avatares subidos y las miniaturas de los enlaces se escriben junto a él, en /app/data/uploads. Ambos se encuentran en el volumen con nombre linkbreeze-data, por lo que la unidad de copia de seguridad es el volumen, no el archivo de base de datos por separado. Si restaura el archivo sin el directorio de cargas, todas las imágenes de la página devuelven un error 404.
Todo lo demás está realmente en esa única base de datos: páginas, enlaces, configuración, tema, suscriptores de correo y filas de analíticas.
Realice la copia con el contenedor detenido:
docker compose stop linkbreeze
docker compose cp linkbreeze:/app/data ./backup-$(date +%F)
docker compose start linkbreezeDeténgalo primero porque copiar una base de datos SQLite mientras un proceso escribe en ella puede capturar una transacción incompleta. La copia se abriría entonces como un archivo corrupto. La página estará fuera de servicio mientras se realiza la copia. La restauración se hace invirtiendo el mismo proceso:
docker compose stop linkbreeze
docker compose cp ./backup-2026-08-14/. linkbreeze:/app/data
docker compose start linkbreeze
docker compose logs -f linkbreezeEl panel también ofrece una exportación JSON, disponible en /api/backup como linkbreeze-backup-YYYY-MM-DD.json. Incluye el perfil, los enlaces y sus secciones, la configuración, los temas guardados y las entradas de fuentes personalizadas. No incluye el historial de analíticas, los suscriptores de correo, la cuenta de administración ni los archivos subidos. Además, al restaurarla se eliminan las filas actuales de las seis tablas que contiene antes de insertar las del archivo. Trátela como una instantánea de configuración para migrar el servicio a otro host o deshacer un error de edición. La copia del volumen es la copia de seguridad.
Aquí se aplican las mismas dos reglas de almacenamiento que en cualquier otro caso de ejecutar SQLite en producción en un VPS. Mantenga la base de datos en el disco local, porque el bloqueo de SQLite no es fiable en un sistema de archivos de red y una página corrupta puede ser la forma de descubrirlo. Si sustituye el volumen con nombre por un montaje bind del host, ejecute primero chown sobre el directorio del host: el contenedor se ejecuta como el usuario no root node, con uid 1000 en node:22-alpine, y ese usuario no puede escribir en un directorio creado por root. Por tanto, la aplicación no puede abrir la base de datos y el contenedor termina durante el arranque. Montajes bind frente a volúmenes con nombre en Compose explica esta diferencia con todos sus detalles.
Los análisis y el aviso de consentimiento que no necesita
Esta es la función que justifica alojar por cuenta propia una página que podría obtener gratis en otro lugar.
Los análisis no usan cookies. Los análisis integrados no establecen ninguna cookie para visitantes ni cargan ningún script de seguimiento de terceros; los análisis externos y las inserciones son funciones opcionales. Un visitante se identifica mediante un hash SHA-256 de la dirección IP, la cadena del agente de usuario y un salt, truncado a 16 caracteres hexadecimales. El salt es, a su vez, un hash de la fecha UTC actual y de su SECRET_KEY, por lo que cambia a medianoche UTC y los hashes del día anterior no pueden compararse con los del día actual. La dirección IP original nunca se escribe en la base de datos.
Los clics se contabilizan en el servidor. Cada enlace http de la página pública apunta a /go/<id> en su propio dominio. Este registra el clic y responde después con una redirección 302 al destino real. Por tanto, el recuento funciona para lectores con JavaScript desactivado y dentro de los navegadores integrados en aplicaciones que bloquean las solicitudes en segundo plano. Las visitas a la página se registran en el servidor cuando se muestra la página pública; /api/track gestiona los eventos de clic y de apertura de ventanas emergentes.
Conviene conocer dos exclusiones. Las solicitudes que incluyen una sesión de administrador válida se omiten, por lo que editar su propia página no aumenta las cifras. También se omiten los agentes de usuario de rastreadores conocidos.
En cuanto al consentimiento, los análisis integrados no usan cookies de seguimiento, pero la normativa sobre cookies también cubre tecnologías similares, incluida la huella digital del dispositivo. El seguimiento sin cookies, por sí solo, no demuestra que no sea necesario mostrar un aviso de consentimiento. Sus obligaciones dependen también del lugar donde vivan sus lectores. Compruébelas junto con las de cualquier análisis externo o inserción que active.
Hay una salvedad que sorprende a algunas personas: si rota SECRET_KEY, el salt diario también cambia, por lo que todos los visitantes que regresen se contabilizarán como nuevos desde ese momento.
¿Por qué está vacía la columna de país de Analytics?
Porque ningún componente de la pila establece una cabecera de país. LinkBreeze obtiene el país de cabeceras del proxy como cf-ipcountry y x-vercel-ip-country. En un VPS situado detrás de su propio Caddy o Nginx, ninguna de esas cabeceras existe, por lo que el país se registra como null y el desglose queda vacío. El contenedor no incluye una base de datos GeoIP.
Hay dos formas de rellenarla. Coloque Cloudflare delante del dominio y habilite su transformación administrada Add visitor location headers para proporcionar cf-ipcountry. O establezca una de esas cabeceras en su propio proxy inverso mediante una consulta GeoIP local.
El problema relacionado es más grave, así que compruébelo. Los controladores de clics y vistas leen primero la dirección del cliente desde X-Forwarded-For, después desde X-Real-IP y usan 0.0.0.0 como alternativa cuando ninguna de las dos cabeceras está presente. Si publica el puerto 3000 directamente en Internet sin ninguna cabecera de dirección, los visitantes con el mismo user agent comparten un hash dentro de cada día UTC; los user agent distintos siguen produciendo hashes diferentes y el hash cambia cada día. Los límites de tasa por IP de 60 eventos por minuto en /api/track y /go/<id> se aplican entonces por separado a toda su audiencia bajo la dirección alternativa. Detrás de la directiva reverse_proxy anterior, Caddy establece la cabecera automáticamente y ambos problemas desaparecen.
Importación desde Linktree y elementos que no se transfieren
El asistente de migración del panel acepta una URL de perfil pública o un archivo exportado. Reconoce páginas de linktr.ee, bento.me, lnk.bio, tap.link, hopp.bio, beacons.ai, solo.to, linkfly, mssg.me y LittleLink, además de exportaciones HTML y JSON genéricas. Para una URL de Linktree o Bento, lee el JSON __NEXT_DATA__ que esas páginas incrustan. En una página estática, lee las etiquetas de anclaje.
Se transfieren el título, la URL, la descripción y la imagen de cada enlace, además de si el enlace corresponde a un perfil social, junto con el nombre visible, la biografía y el avatar. Antes de escribir nada en la base de datos, puede elegir qué enlaces encontrados conservar.
No se transfieren el historial de analíticas, el tema ni la disposición, los suscriptores de correo electrónico, las fechas de publicación programadas ni ningún elemento que la plataforma anterior mantenga detrás de su propio inicio de sesión. Tenga previsto reconstruir el aspecto manualmente y acepte que el historial de clics anterior seguirá en el servicio antiguo.
El importador obtiene la URL desde su servidor y no desde el navegador, por lo que rechaza las direcciones que no sean públicas. Private/local URLs are not allowed significa que proporcionó una dirección dentro de su propia red. El rechazo es intencionado: sin esta protección, cualquier persona con acceso al panel podría usar su servidor para sondear máquinas a las que sólo su servidor puede acceder. Los otros mensajes que puede ver son Only http and https URLs are allowed, Request timed out y Response too large.
El scraping depende del marcado de terceros. En v1.5.1, el importador corrige un error de Linktree que obtenía los enlaces de afiliados de la plataforma en lugar de los enlaces propios del perfil. Actualice antes de importar desde Linktree. Los perfiles cuyos enlaces sólo se muestran en el navegador todavía requieren la pestaña File o una introducción manual. Si el asistente no encuentra nada en una página que claramente contiene enlaces, añádalos manualmente en lugar de esperar una corrección. Si en realidad necesita enlaces cortos medibles y no una página de perfil, un acortador de URL autoalojado como Shlink cumple esa función y funciona sin problemas en el mismo servidor.
Actualizar una implementación fijada
# edit the image tag in docker-compose.yml, then
docker compose pull
docker compose up -d
docker compose logs -f linkbreezeLas migraciones del esquema se ejecutan automáticamente cuando se inicia el contenedor. No existe una forma documentada de ejecutarlas en sentido inverso, así que haga primero una copia del volumen. Una actualización que no se puede revertir sólo es segura si puede restaurar el estado anterior.
El panel debe mostrar un aviso cuando existe una versión más reciente. La versión fijada v1.4.1 comprueba un archivo pequeño de versión en GitHub; desde v1.5.0, publicada el 24 October 2026, la comprobación del aviso obtiene linkbreeze.omnirise.dev/latest-version.json. Los resultados se almacenan en caché durante 24 horas, pero el botón manual Check now omite esa caché, también en v1.4.1. Estas comprobaciones no envían datos de la instancia en la carga útil de la solicitud. El registro de cambios indica que v1.2.0 a v1.4.0 consultaban una dirección que respondía con 404 y nunca mostraban el aviso. Hasta que ejecute una versión con el endpoint del sitio web, no espere el aviso: supervise por su cuenta el registro de cambios en linkbreeze.omnirise.dev/changelog. En v1.5.1, Settings también incluye una tarjeta de estado de actualización que comprueba GitHub y el sitio web, con un botón Recheck que omite la caché. Lea las notas de la versión antes de cambiar la etiqueta, porque en esta fase del proyecto una versión menor puede cambiar valores predeterminados de los que depende.
Modos de fallo y cadenas que verá
manifest unknown al extraer la imagen. La etiqueta está escrita con el formato incorrecto para esa versión. Desde v1.4.0, las etiquetas incluyen v, así que use :v1.4.1. Las versiones de GHCR hasta v1.3.2 usan números sin prefijo, como :1.2.7, y Docker Hub también incluye etiquetas de versiones más recientes, como v1.5.1.
no matching manifest for linux/arm64/v8 in the manifest list entries. Fijó una versión anterior a v1.4.0, que se publicó sólo para amd64. Cambie la versión fijada a v1.4.1, que incluye una compilación para arm64. Una placa arm/v7 de 32 bits produce el mismo tipo de error con todas las versiones, porque esa plataforma no se compila de forma intencionada.
El contenedor muestra unhealthy aunque la página carga correctamente. Un healthcheck del archivo compose ejecuta curl, que no está incluido en la imagen. Elimínelo y deje que se ejecute el healthcheck wget propio de la imagen.
Caddy muestra un error de certificado o no muestra nada. Compruebe docker compose logs caddy. Confirme que el registro A apunta a este VPS y que los puertos 80 y 443 son accesibles. Caddy puede validarse mediante un desafío HTTP en el puerto 80 o un desafío TLS-ALPN en el puerto 443.
El número de visitantes únicos permanece en 1. Compruebe si el proxy establece X-Forwarded-For o X-Real-IP. Sin ninguna de esas cabeceras, los visitantes con agentes de usuario idénticos comparten un hash durante cada día UTC. El hash también incluye una sal diaria, por lo que la ausencia de cabeceras no hace que todos los visitantes tengan siempre el mismo hash.
El contenedor se detiene justo después de iniciar, aunque ayer funcionaba. Si cambió de un volumen con nombre a un montaje bind del host, el directorio de datos pertenece a root y la aplicación se ejecuta con uid 1000, por lo que no puede abrir el archivo de base de datos. sudo chown -R 1000:1000 el directorio del host.
Las solicitudes de seguimiento reciben HTTP 429. Se alcanzó el límite por IP de /api/track. El límite independiente de /go/<id> omite el registro del clic, pero sigue devolviendo la redirección 302 al destino.
FAQ
¿LinkBreeze está listo para un enlace público en la biografía?
Es un proyecto reciente, y la primera versión se publicó el 1 July 2026. Publicó 22 versiones etiquetadas entre esa fecha y v1.4.1, el 23 September 2026; la mayoría se publicaron antes de mediados de August, por lo que el comportamiento ha cambiado rápidamente. Las versiones v1.5.0 y v1.5.1 llegaron el 24 y el 27 October 2026, y el repositorio canónico de GitHub es público desde el 2 November 2026. La licencia MIT y el archivo SQLite local permiten mantener una página operativa aunque se detenga el desarrollo, pero una aplicación web pública sin correcciones de seguridad se convierte en una responsabilidad, así que considérelo software que deberá mantener actualizado, no algo que se instala una sola vez.
¿Qué etiqueta de imagen de LinkBreeze debo ejecutar?
Ejecute la etiqueta de versión, por ejemplo docker.io/omnirise/linkbreeze:v1.4.1, y cámbiela de forma deliberada. Desde v1.4.0, el flujo de publicación sube latest y la etiqueta de git con su v inicial, por lo que :1.4.1 sin v no existe y Docker responde manifest unknown. Hasta v1.3.2, las versiones son lo contrario: en GHCR sólo existen números sin prefijo. La imagen se compila para linux/amd64 y linux/arm64 desde v1.4.0, por lo que una VPS arm64 la descarga directamente sin compilación local.
¿Por qué el desglose por país permanece vacío en las estadísticas de LinkBreeze?
LinkBreeze lee el país del visitante desde cabeceras del proxy como cf-ipcountry o x-vercel-ip-country y no incluye su propia base de datos GeoIP. Una VPS detrás de su propio Caddy o Nginx no establece ninguna de esas cabeceras, por lo que el país se almacena como null. Coloque Cloudflare delante del dominio y active su transformación gestionada Add visitor location headers, o configure el proxy inverso para que establezca una de esas cabeceras mediante una consulta GeoIP local.
¿Qué debo respaldar exactamente y cómo lo restauro?
Respalde todo el volumen linkbreeze-data, no sólo el archivo de base de datos. /app/data/linkbreeze.db contiene cada enlace, página, configuración, suscriptor y fila de estadísticas, y /app/data/uploads contiene las imágenes de avatar y miniaturas a las que hace referencia la página. Detenga el contenedor, ejecute docker compose cp linkbreeze:/app/data ./backup-$(date +%F) y vuelva a iniciarlo. Para restaurarlo, copie el directorio de nuevo en el contenedor detenido y arránquelo. La exportación JSON del panel es una instantánea de configuración del perfil, los enlaces, la configuración, los temas y las entradas de fuentes. No contiene estadísticas ni imágenes.
¿La importación desde Linktree incluye mis estadísticas y mi tema?
No. El asistente de migración lee los títulos, las URL, las descripciones y las imágenes de los enlaces del perfil público anterior, además del nombre visible, la biografía y el avatar. El historial de estadísticas, el tema, los suscriptores de correo electrónico y las fechas de publicación programada no se transfieren. Vuelva a crear el diseño en el editor de temas después de la importación y espere que el historial de clics permanezca en la plataforma anterior.