Cómo autoalojar Shlink en 2026: dominios, claves de API y estadísticas

Autoalojar Shlink resulta interesante cuando haces el primer redeploy, no cuando ejecutas el primer docker run. Si los enlaces generados usan HTTP o las migraciones no pueden acceder a la base de datos, Docker puede seguir mostrando un proceso perfectamente saludable. El despliegue siguiente se organiza en torno a comportamientos observables: crear una URL corta mediante la API, seguir su redirección, registrar visitas y consultar las estadísticas desde el cliente web.

La función de Shlink está clara: un acortador de enlaces API-first con estadísticas. Esta descripción nos indica qué debe permanecer público, qué debe seguir siendo privado y qué debe poder reconstruir una copia de seguridad.

De qué depende Shlink

En Shlink, la salud del proceso y la salud del producto son independientes. El puerto 8080 puede responder aunque la transacción orientada al usuario siga fallando. El contrato de red de Shlink requiere Postgres o MariaDB, además de Redis opcional para producción. Mantén los endpoints privados en DNS interno, permite únicamente las llamadas salientes necesarias y proporciona a Shlink una credencial de servicio con permisos limitados.

Usa este ejercicio de preparación después de cambios de configuración relevantes: crea una URL corta mediante la API, sigue su redirección, registra visitas y consulta las estadísticas desde el cliente web. Mantén las comprobaciones externas costosas fuera de las sondas de liveness para que una interrupción de un proveedor no provoque un bucle de reinicios. El trabajo de capacidad debe hacer seguimiento del rendimiento de las redirecciones, las escrituras en la base de datos, las descargas de geolocalización y el comportamiento de la caché, que refleja mejor la presión real sobre Shlink que las solicitudes de páginas.

Los volúmenes son solo la primera capa de recuperación

No se espera que haya estado de aplicación escribible dentro de la imagen estándar de Shlink. Conserva la base de datos, las claves de API y cualquier dato de visitas importado, incluido el digest fijado y la configuración de rutas revisada, en lugar de hacer una copia de seguridad de un sistema de archivos vacío del contenedor.

Crea Shlink desde cero en otro host y verifica que se recuperan los dominios, los códigos cortos, las etiquetas y los registros de visitas, y que todas las URL cortas comprobadas se redirigen exactamente igual. Si añades una base de datos independiente, un servidor de salas o una capa de autenticación, asigna a cada componente un responsable de recuperación explícito. La guía de Git a producción muestra cómo un artefacto reproducible sustituye a una copia de seguridad del contenedor.

Registra el comando de reconstrucción y la prueba con resultados conocidos junto con la release. Un plan de recuperación sin estado funciona al reproducir el comportamiento a partir de entradas fiables; no debe depender de copiar un contenedor en ejecución opaco.

Protege la parte valiosa de Shlink

Un despliegue seguro de Shlink comienza eliminando autoridad. Evita exponer la clave de API REST o cambiar el dominio público después de publicar los enlaces; en su lugar, mantén las claves de API fuera del código del navegador, usa HTTPS y restringe la administración mientras mantienes públicas las redirecciones.

DEFAULT_DOMAIN es configuración, no un secreto; mantén su valor explícito y protege por separado las credenciales que usa Shlink. Restringe las rutas administrativas, usa DNS privado para las dependencias y revisa cada bind mount. Cuando los logs se envíen de forma centralizada, filtra los secretos y el contenido privado antes de que abandonen el servidor.

Convierte la prueba de humo de Shlink en una comprobación de release

En Shlink, define una transacción válida antes del lanzamiento: crea una URL corta mediante la API, sigue su redirección, registra visitas y consulta las estadísticas desde el cliente web. Guarda en el control de versiones sus requisitos previos, la respuesta esperada y los pasos de limpieza, sin incluir valores secretos. Fija la imagen usada para establecer esa referencia.

Usa la transacción para validar un reemplazo y una restauración independiente. El servicio restaurado solo es aceptable cuando se recuperan los dominios, los códigos cortos, las etiquetas y los registros de visitas, y todas las URL cortas comprobadas se redirigen exactamente igual. Al mismo tiempo, observa el rendimiento de las redirecciones, las escrituras en la base de datos, las descargas de geolocalización y el comportamiento de la caché, y convierte la parte más lenta o limitada en una alerta de nivel de servicio.

La validación también necesita un caso negativo: deniega temporalmente al usuario de prueba el acceso a Postgres o MariaDB, además de Redis opcional para producción. Confirma que Shlink produce un error accionable sin perder datos, restaura la condición válida y repite la transacción correcta conocida. Mantener ambos resultados evita que un endpoint de health superficial se convierta en la única evidencia de producción.

Inicia Shlink sin ocultar las piezas móviles

El siguiente comando hace visible el límite del contenedor sin fingir que aprovisiona todos los servicios externos.

docker run -d \
  --name shlink \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -e DEFAULT_DOMAIN=go.example.com \
  shlinkio/shlink:stable

Antes de abrir el ingress, inspecciona el entorno resuelto, los montajes y el listener. Añade los ajustes de conexión revisados para Postgres o MariaDB, además de Redis opcional para producción; usa nombres privados para los servicios privados. Un lanzamiento correcto termina cuando puedes crear una URL corta mediante la API, seguir su redirección, registrar visitas y consultar las estadísticas desde el cliente web, no cuando docker ps muestra Up.

Proporciona a Shlink una dirección canónica

El límite público de Shlink debe ser un único hostname canónico, TLS automático y un único destino interno en 8080. Configura DEFAULT_DOMAIN y IS_HTTPS_ENABLED antes de crear URL cortas para que los clientes vuelvan a una dirección que el servicio reconozca.

Si la transacción de aceptación falla, clasifica el primer error. Los problemas de DNS, certificados y 502 pertenecen a la lista de comprobación de validación de TLS. La condición «los enlaces generados usan HTTP o las migraciones no pueden acceder a la base de datos» pertenece al lado de la aplicación, después de que una solicitud haya llegado correctamente a Shlink.

Diagnostica un Shlink que parece saludable

En Shlink, supervisa una transacción en lugar de un proceso: crea una URL corta mediante la API, sigue su redirección, registra visitas y consulta las estadísticas desde el cliente web. Combina su latencia y tasa de errores con el rendimiento de las redirecciones, las escrituras en la base de datos, las descargas de geolocalización y el comportamiento de la caché para que una alerta identifique el componente limitado.

El ensayo de actualización debe cubrir que las migraciones de la base de datos y la compatibilidad de la API deben prepararse por etapas, porque los enlaces cortos publicados no pueden esperar una reparación manual. Restaura, migra y ejecuta la transacción antes de sustituir el servicio en producción. Si los enlaces generados usan HTTP o las migraciones no pueden acceder a la base de datos, no borres datos para que el arranque aparezca en verde; compara la versión, las variables, los montajes y la accesibilidad de las dependencias, en ese orden.

Mantén Shlink explícito mientras Dockup gestiona el routing

El despliegue de Shlink con un clic de Dockup debe hacer que el reemplazo sea seguro: la ruta debe seguir apuntando a 8080, los secretos no deben incorporarse a la imagen y las rutas persistentes deben volver a estar disponibles en el contenedor nuevo. El mismo despliegue puede ejecutarse en la infraestructura de Dockup o en una máquina conectada.

Completa el trabajo específico de la aplicación conectando y probando Postgres o MariaDB, además de Redis opcional para producción, aplicando la dirección pública canónica y ejecutando esta comprobación de aceptación: crea una URL corta mediante la API, sigue su redirección, registra visitas y consulta las estadísticas desde el cliente web. Añade el resultado de la restauración al runbook antes de que lleguen usuarios reales.

Preguntas frecuentes

¿Qué necesita Shlink para un despliegue en producción?

Enruta el contenedor de Shlink en el puerto 8080 a través de un único origen HTTPS. El requisito de red de soporte es Postgres o MariaDB, además de Redis opcional para producción. No consideres que Shlink está listo hasta que puedas crear una URL corta mediante la API, seguir su redirección, registrar visitas y consultar las estadísticas desde el cliente web.

¿Qué datos de Shlink deben incluirse en una copia de seguridad?

La imagen estándar de Shlink no tiene ningún montaje obligatorio para los datos de la aplicación. Conserva su configuración de despliegue y haz copias de seguridad de cualquier estado conectado por separado; la recuperación se considera correcta cuando se recuperan los dominios, los códigos cortos, las etiquetas y los registros de visitas, y todas las URL cortas comprobadas se redirigen exactamente igual.

¿Shlink necesita HTTPS detrás de un reverse proxy?

Usa HTTPS para el origen público de Shlink y mantén el puerto 8080 en la ruta interna. Aplica correctamente el ajuste de Shlink: configura DEFAULT_DOMAIN y IS_HTTPS_ENABLED antes de crear URL cortas. En Shlink, HTTPS protege las credenciales o el contenido del usuario durante el tránsito y mantiene coherente el comportamiento del cliente sensible al origen.

¿Cómo debe probarse una actualización de Shlink?

Restaura el estado actual de Shlink en un despliegue aislado, aplica la versión candidata y repite su transacción de aceptación. Presta especial atención, porque las migraciones de la base de datos y la compatibilidad de la API deben prepararse por etapas, ya que los enlaces cortos publicados no pueden esperar una reparación manual. Conserva la imagen anterior de Shlink hasta comprender los límites de migración de datos y de rollback.