Cómo configurar tu propio acortador de

Qué estamos configurando y por qué

En una era donde cada carácter cuenta y las URL largas y torpes pueden ahuyentar a los usuarios y arruinar la apariencia de un mensaje, los servicios de acortamiento de enlaces se han convertido en una herramienta indispensable. Shlink es una solución autoalojada (self-hosted) de código abierto que le permite crear su propio servicio de acortamiento de URL, completamente controlado por usted. A diferencia de alternativas comerciales populares como Bitly o Rebrandly, Shlink le brinda total libertad y propiedad de los datos, así como la capacidad de usar sus propios dominios para la marca de los enlaces.

Al final de esta guía, tendrá un acortador de URL Shlink completamente funcional, desplegado en su propio VPS. Esto significa que podrá crear enlaces cortos y memorables que apuntarán a su dominio (por ejemplo, my.link/abc en lugar de long-and-ugly-url.com/some/path/to/resource). Además del acortamiento básico, Shlink ofrece un rico conjunto de funciones: análisis detallado de clics (número de clics, geografía, navegadores, sistemas operativos), creación de códigos QR para cada enlace, la capacidad de establecer contraseñas en los enlaces, límites de clics y fechas de vencimiento, así como una potente API para la integración con otros de sus servicios. Podrá gestionar todas estas funciones a través de una cómoda interfaz web o la línea de comandos.

¿Por qué autoalojado en un VPS y no servicios gestionados en la nube? La elección de un VPS propio se debe a varias ventajas clave. Primero, es el control total sobre los datos. Toda la información sobre sus enlaces y su análisis se almacena en su servidor, no en los servidores de un proveedor externo. Esto es crítico para proyectos que requieren mayor confidencialidad o cumplimiento de estrictos requisitos regulatorios. Segundo, es la personalización. Puede configurar Shlink según sus necesidades, integrarlo con otras herramientas, usar su propio dominio de marca sin las restricciones que a menudo imponen los planes gratuitos de los servicios en la nube. Tercero, es el ahorro a largo plazo. Aunque el alquiler de un VPS requiere cierta inversión inicial y tiempo de configuración, para proyectos de alta carga o a largo plazo, a menudo resulta significativamente más barato que las suscripciones mensuales a servicios comerciales, especialmente con un gran volumen de enlaces o análisis. Finalmente, es una excelente manera de profundizar sus conocimientos en la administración de servidores y el trabajo con Docker, lo cual es una habilidad valiosa para cualquier desarrollador o especialista técnico.

Las alternativas a Shlink incluyen una multitud de soluciones comerciales como Bitly, Rebrandly, Short.io, TinyURL, así como otras opciones autoalojadas, por ejemplo, Kutt o Polr. Sin embargo, Shlink se destaca por su madurez, desarrollo activo, rica funcionalidad y soporte para Docker, lo que lo convierte en una opción ideal para el despliegue en un VPS.

Qué configuración de VPS se necesita para esta tarea

Para desplegar Shlink con Docker y una base de datos en un VPS, es importante elegir los recursos de hardware adecuados. Shlink en sí mismo es bastante ligero, pero Docker, la base de datos (por ejemplo, MariaDB o PostgreSQL) y el servidor web (Caddy) requieren un cierto mínimo.

Requisitos mínimos:

• CPU: 1 vCPU (núcleo virtual). Para proyectos pequeños y pruebas, esto será suficiente.
• RAM: 1 GB. Este es el mínimo absoluto. Docker Engine, el sistema operativo y la base de datos consumen una parte significativa de esta memoria, dejando poco para Shlink. Pueden surgir problemas durante picos de carga o actualizaciones.
• Disco: 20 GB NVMe/SSD. NVMe o SSD son altamente deseables para el rendimiento de la base de datos. 20 GB serán suficientes para el sistema operativo, las imágenes de Docker, los datos de Shlink y los registros.
• Red: 100 Mbps con tráfico ilimitado o con un gran margen (a partir de 1 TB al mes). Shlink no es un servicio muy dependiente de la red, a menos que espere millones de clics al día.

Plan de VPS recomendado para la mayoría de los casos (válido para 2026):

Para un funcionamiento cómodo y la posibilidad de escalar en el futuro, así como para garantizar la estabilidad, se recomienda la siguiente configuración:

• CPU: 2 vCPU. Asegurará un funcionamiento fluido de todos los componentes y permitirá procesar más solicitudes simultáneamente.
• RAM: 2-4 GB. 2 GB serán suficientes para la mayoría de los proyectos medianos, 4 GB proporcionarán un gran margen de seguridad y permitirán ejecutar servicios adicionales si es necesario.
• Disco: 40-80 GB NVMe/SSD. Un mayor volumen de disco proporcionará espacio para la expansión de la base de datos, los registros y posibles copias de seguridad. NVMe acelerará significativamente las operaciones de disco.
• Red: 1 Gbps con tráfico a partir de 5 TB al mes. Un puerto Gigabit y un volumen de tráfico suficiente garantizarán una alta velocidad de carga y procesamiento de solicitudes, incluso si su acortador de URL se vuelve muy popular.

Encontrar un VPS con las características indicadas no será difícil en la mayoría de los proveedores. Por ejemplo, se puede tomar un VPS con 2 vCPU, 4 GB de RAM y un disco NVMe de 80 GB, lo que proporcionará un excelente rendimiento y margen para el futuro.

Cuándo se necesita un dedicado, no un VPS:

Un servidor dedicado (dedicated server) se vuelve necesario cuando su acortador de URL comienza a manejar volúmenes muy grandes de tráfico (decenas o cientos de millones de clics al mes), cuando se requiere el máximo rendimiento de la base de datos, o si planea alojar muchas otras aplicaciones que consumen muchos recursos en el mismo servidor. Además, los servidores dedicados ofrecen un mayor nivel de aislamiento y, a menudo, mayores posibilidades de personalización del hardware. Para Shlink, esto generalmente no es necesario, a menos que esté construyendo un servicio global con miles de millones de redirecciones.

Ubicación: en qué influye

La elección de la ubicación del VPS es importante por varias razones:

• Latencia: Cuanto más cerca esté el servidor de su audiencia principal o de los servidores a los que apuntarán los enlaces acortados, menor será la latencia en la redirección. Para un acortador de URL, esto no es crítico, ya que la redirección en sí ocurre muy rápidamente, pero para la capacidad de respuesta general del panel de administración y la API, puede ser notable.
• Legislación: Dependiendo de dónde esté ubicado físicamente el servidor, se aplicarán las leyes de ese país con respecto al almacenamiento de datos, la privacidad, etc. Asegúrese de que la jurisdicción elegida cumpla con sus requisitos.
• Disponibilidad: Algunas regiones pueden ofrecer una conexión de red más estable y rápida, así como una mejor conectividad con diferentes partes del mundo.

Generalmente se recomienda elegir una ubicación que esté geográficamente cerca de su público objetivo o de usted mismo para simplificar la gestión.

Preparación del servidor

Después de obtener acceso a su nuevo VPS, lo primero que debe hacer es realizar una configuración mínima para garantizar la seguridad y la comodidad de uso. Utilizaremos la distribución Ubuntu Server 24.04 LTS (versión actual para 2026) como la opción más común y bien documentada.

1. Conexión por SSH

Conéctese al servidor como usuario root (o el usuario proporcionado por el proveedor de hosting) a través de SSH. Reemplace con la dirección IP de su servidor.

ssh root@

Si utiliza una contraseña, el sistema la solicitará. Si utiliza claves SSH, asegúrese de que su clave pública esté añadida al servidor.

2. Actualización del sistema

Siempre comience actualizando la lista de paquetes y su instalación a la última versión. Esto asegurará que tenga todas las últimas correcciones de seguridad y estabilidad.

sudo apt update          # Actualiza la lista de paquetes disponibles
sudo apt upgrade -y      # Instala todas las actualizaciones disponibles sin confirmación
sudo apt autoremove -y   # Elimina paquetes innecesarios

3. Creación de un nuevo usuario con permisos sudo

Trabajar como usuario root no es seguro. Cree un nuevo usuario y concédale permisos sudo.

sudo adduser shlinkuser                  # Crea un nuevo usuario con el nombre shlinkuser
sudo usermod -aG sudo shlinkuser         # Añade el usuario shlinkuser al grupo sudo

Después de crear el usuario, asígnele una contraseña segura. Ahora puede salir de root e iniciar sesión con el nuevo usuario:

exit                                     # Salir de root
ssh shlinkuser@             # Iniciar sesión como el nuevo usuario

4. Configuración de claves SSH para el nuevo usuario (recomendado)

Para mejorar la seguridad y la comodidad, configure el inicio de sesión con claves SSH para shlinkuser. Si aún no tiene una clave SSH en su máquina local, créela:

ssh-keygen -t rsa -b 4096 -C "[email protected]" # Crea una nueva clave SSH (en su máquina local)

Luego, copie la clave pública al servidor:

ssh-copy-id shlinkuser@     # Copia la clave pública al servidor

O añada manualmente el contenido del archivo ~/.ssh/id_rsa.pub (en su máquina local) al archivo ~/.ssh/authorized_keys en el servidor (para el usuario shlinkuser).

Después de esto, puede deshabilitar el inicio de sesión con contraseña para SSH, editando el archivo /etc/ssh/sshd_config. Busque las líneas:

PasswordAuthentication yes

Y cámbiela a:

PasswordAuthentication no

También se recomienda deshabilitar el inicio de sesión para el usuario root por SSH, cambiando:

PermitRootLogin yes

a:

PermitRootLogin no

Después de los cambios, reinicie el servicio SSH:

sudo systemctl restart sshd

Importante: ¡Asegúrese de poder iniciar sesión con la clave SSH antes de deshabilitar el inicio de sesión con contraseña! De lo contrario, podría perder el acceso al servidor.

5. Instalación y configuración del firewall UFW

El firewall Uncomplicated Firewall (UFW) es fácil de configurar y mejora significativamente la seguridad del servidor, bloqueando las conexiones entrantes no deseadas.

sudo apt install ufw -y                 # Instala UFW
sudo ufw allow OpenSSH                  # Permite conexiones SSH (puerto 22)
sudo ufw allow http                     # Permite conexiones HTTP (puerto 80)
sudo ufw allow https                    # Permite conexiones HTTPS (puerto 443)
sudo ufw enable                         # Habilita UFW
sudo ufw status                         # Comprueba el estado de UFW

La salida de sudo ufw status debería mostrar que SSH, HTTP y HTTPS están permitidos.

6. Instalación de Fail2Ban

Fail2Ban escanea los registros del servidor (por ejemplo, SSH, servidor web) en busca de actividad sospechosa (múltiples intentos fallidos de inicio de sesión) y bloquea temporal o permanentemente las direcciones IP de los atacantes.

sudo apt install fail2ban -y            # Instala Fail2Ban
sudo systemctl enable fail2ban          # Habilita el inicio automático de Fail2Ban al arrancar el sistema
sudo systemctl start fail2ban           # Inicia el servicio Fail2Ban
sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local # Copia la configuración para cambios locales

Puede editar /etc/fail2ban/jail.local para una configuración más detallada, por ejemplo, cambiar bantime (tiempo de bloqueo) o findtime (período en el que se cuentan los intentos fallidos). Por defecto, SSH ya está protegido.

Instalación de software — paso a paso

Ahora que el servidor está preparado, pasemos a la instalación del software necesario: Docker Engine y Docker Compose. Utilizaremos las versiones actuales disponibles en 2026.

1. Instalación de Docker Engine

Docker Engine es la plataforma principal para ejecutar contenedores. Lo instalaremos desde el repositorio oficial de Docker para tener siempre las versiones más recientes.

# Actualiza la lista de paquetes e instala las dependencias para apt
sudo apt update
sudo apt install ca-certificates curl gnupg lsb-release -y

# Añade la clave GPG oficial de Docker
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Añade el repositorio de Docker a sources.list
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Actualiza la lista de paquetes apt después de añadir el repositorio de Docker
sudo apt update

# Instala Docker Engine, Docker CLI y containerd.io
# Versiones actuales para 2026: Docker Engine 26.x, Docker CLI 26.x
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

# Comprueba que Docker esté instalado y en ejecución
sudo systemctl status docker

La salida de sudo systemctl status docker debería mostrar que Docker está activo (active (running)).

2. Añadir usuario al grupo Docker

Para evitar el uso constante de sudo al trabajar con Docker, añada su usuario al grupo docker.

sudo usermod -aG docker shlinkuser       # Añade shlinkuser al grupo docker
newgrp docker                            # Activa los cambios para la sesión actual

Ahora puede verificar la instalación de Docker sin sudo:

docker run hello-world                   # Ejecuta el contenedor de prueba 'hello-world'

Si ve el mensaje de bienvenida de Docker, significa que todo está configurado correctamente.

3. Creación de un directorio para el proyecto Shlink

Crearemos un directorio donde se almacenarán todos los archivos del proyecto Shlink.

mkdir ~/shlink-docker                    # Crea el directorio shlink-docker en el directorio de inicio del usuario
cd ~/shlink-docker                       # Cambia al directorio creado

4. Descarga del archivo Docker Compose para Shlink

Shlink proporciona un archivo oficial docker-compose.yml que incluye todos los servicios necesarios: Shlink en sí, una base de datos (MariaDB por defecto) y el servidor web Caddy para proxy inverso y HTTPS. Lo utilizaremos como base.

Para 2026, las imágenes oficiales de Shlink y Caddy se mantienen activamente. Shlink versión 4.x y Caddy versión 2.x.

# Descarga el archivo oficial docker-compose.yml
curl -sL https://raw.githubusercontent.com/shlinkio/shlink-web-client/master/docker/docker-compose.yml -o docker-compose.yml

# Descarga el archivo de ejemplo .env
curl -sL https://raw.githubusercontent.com/shlinkio/shlink-web-client/master/docker/.env.example -o .env

# Descarga el archivo de ejemplo Caddyfile
curl -sL https://raw.githubusercontent.com/shlinkio/shlink-web-client/master/docker/Caddyfile -o Caddyfile

Ahora tiene tres archivos clave en el directorio ~/shlink-docker: docker-compose.yml, .env y Caddyfile. Los editaremos en el siguiente paso.

Configuración

Después de descargar los archivos base, es necesario configurarlos para su entorno. Esto incluye variables de entorno, configuración de la base de datos, configuración del servidor web Caddy y registros DNS.

1. Configuración del archivo .env

El archivo .env contiene variables de entorno que Docker Compose utiliza para configurar los servicios. Edítelo, reemplazando los marcadores de posición con sus valores. Abra el archivo para editar:

nano .env

Ejemplo del contenido de .env (asegúrese de cambiar DB_ROOT_PASSWORD, DB_PASSWORD, DEFAULT_DOMAIN y API_KEY):

# Database configuration
DB_DRIVER=mariadb
DB_HOST=db
DB_PORT=3306
DB_NAME=shlink
DB_USER=shlink
DB_PASSWORD=your_strong_db_password_here # ¡Obligatorio cambiar!
DB_ROOT_PASSWORD=your_strong_db_root_password_here # ¡Obligatorio cambiar!

# Shlink configuration
DEFAULT_DOMAIN=your-shlink-domain.com # Reemplace con su dominio (por ejemplo, s.example.com)
DEFAULT_BASE_URL=https://your-shlink-domain.com # Reemplace con su dominio
DEFAULT_TITLE=My Custom Shlink
GEOLITE_LICENSE_KEY=your_geolite_license_key # Opcional, para geo-análisis. Obtener en MaxMind.
API_KEY=your_shlink_api_key_here # ¡Obligatorio generar y cambiar!
INITIAL_API_KEY=your_initial_api_key_for_first_login # Opcional, para el primer inicio de sesión en el panel de administración
SHLINK_WEB_CLIENT_URL=https://shlink-web.your-shlink-domain.com # URL para el cliente web, si lo despliega por separado

Explicaciones:

• DB_PASSWORD y DB_ROOT_PASSWORD: Es muy importante usar contraseñas únicas y seguras.
• DEFAULT_DOMAIN: Este es el dominio que se utilizará para los enlaces acortados. Por ejemplo, si desea que los enlaces se vean como s.example.com/xyz, entonces aquí debe ser s.example.com. Asegúrese de que este dominio (o subdominio) apunte a la dirección IP de su VPS.
• API_KEY: Genere una clave larga y aleatoria. Se utilizará para la autenticación al acceder a la API de Shlink y en el cliente web.
• GEOLITE_LICENSE_KEY: Si desea utilizar geoanálisis, debe obtener una clave de licencia gratuita de GeoLite2 de MaxMind (se requiere registro). Sin ella, el geoanálisis no funcionará.

2. Configuración del archivo Caddyfile

Caddy actuará como un proxy inverso, reenviando las solicitudes a Shlink y gestionando automáticamente los certificados HTTPS a través de Let's Encrypt. Abra el archivo para editar:

nano Caddyfile

Reemplace your-shlink-domain.com con su dominio (el mismo que en .env).

{
  email [email protected] # Reemplace con su email para notificaciones de Let's Encrypt
}

your-shlink-domain.com { # Reemplace con su dominio (por ejemplo, s.example.com)
  reverse_proxy shlink:8080
}

# Si está desplegando el cliente web de Shlink por separado, añada una sección para él:
# shlink-web.your-shlink-domain.com { # Reemplace con su dominio para el cliente web
#   root * /app/dist
#   file_server
#   try_files {path} {path}/ /index.html
# }

Explicaciones:

• email [email protected]: Especifique su dirección de correo electrónico válida. Let's Encrypt la utilizará para las notificaciones de certificados.
• your-shlink-domain.com: Este es el dominio a través del cual su Shlink será accesible. Caddy obtendrá automáticamente un certificado HTTPS para él.
• shlink:8080: Este es el nombre interno del servicio Shlink dentro de Docker Compose y su puerto.
• (Opcional) Si está desplegando el cliente web de Shlink (shlink-web-client) en el mismo Docker Compose, es posible que necesite una sección separada para él, como se muestra en el ejemplo comentado. En esta guía, nos centramos en Shlink en sí, y el cliente web se puede conectar más tarde a través de la API.

3. Configuración del archivo docker-compose.yml (si es necesario)

Normalmente, el archivo docker-compose.yml descargado es adecuado sin cambios, pero vale la pena revisarlo. Define tres servicios:

• db: Base de datos (MariaDB).
• shlink: El servicio Shlink en sí.
• caddy: Servidor web/proxy inverso.

Asegúrese de que las versiones de las imágenes estén actualizadas (por ejemplo, shlinkio/shlink:4.0.0, mariadb:11.3, caddy:2.7-alpine para 2026). Si planea usar PostgreSQL, deberá cambiar la imagen de db y las variables correspondientes en .env.

# Ejemplo de docker-compose.yml (abreviado)
version: '3.8'

services:
  db:
    image: mariadb:11.3 # Versión actual de MariaDB para 2026
    restart: unless-stopped
    env_file:
      - .env
    volumes:
      - shlink_db_data:/var/lib/mysql
    environment:
      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
      MARIADB_DATABASE: ${DB_NAME}
      MARIADB_USER: ${DB_USER}
      MARIADB_PASSWORD: ${DB_PASSWORD}

  shlink:
    image: shlinkio/shlink:4.0.0 # Versión actual de Shlink para 2026
    restart: unless-stopped
    env_file:
      - .env
    ports:
      - "8080:8080" # Puerto interno de Shlink
    depends_on:
      - db
    environment:
      DB_DRIVER: ${DB_DRIVER}
      DB_HOST: ${DB_HOST}
      DB_PORT: ${DB_PORT}
      DB_NAME: ${DB_NAME}
      DB_USER: ${DB_USER}
      DB_PASSWORD: ${DB_PASSWORD}
      DEFAULT_DOMAIN: ${DEFAULT_DOMAIN}
      DEFAULT_BASE_URL: ${DEFAULT_BASE_URL}
      DEFAULT_TITLE: ${DEFAULT_TITLE}
      GEOLITE_LICENSE_KEY: ${GEOLITE_LICENSE_KEY}
      API_KEY: ${API_KEY}
      INITIAL_API_KEY: ${INITIAL_API_KEY}

  caddy:
    image: caddy:2.7-alpine # Versión actual de Caddy para 2026
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - shlink_caddy_data:/data
    depends_on:
      - shlink

volumes:
  shlink_db_data:
  shlink_caddy_data:

4. Configuración de registros DNS

Antes de iniciar Shlink, debe asegurarse de que su dominio (o subdominio, por ejemplo, s.example.com) apunte a la dirección IP de su VPS. Vaya al panel de control de su registrador de dominios (o proveedor de DNS) y cree un registro A:

• Tipo: A
• Nombre/Host: su subdominio (por ejemplo, s, si el dominio completo es s.example.com) o @, si usa el dominio principal.
• Valor/Dirección IP: la dirección IP de su VPS.

La propagación de los registros DNS puede tardar desde unos minutos hasta varias horas. Puede verificar el estado con el comando dig en su máquina local:

dig +short your-shlink-domain.com

Debería devolver la dirección IP de su VPS.

5. Inicio de Shlink con Docker Compose

Después de todas las configuraciones, estando en el directorio ~/shlink-docker, inicie todos los servicios:

docker compose up -d                     # Iniciamos los contenedores en segundo plano

Esto descargará las imágenes de Docker necesarias (si no están localmente), creará los contenedores, configurará la red e iniciará los servicios. El primer inicio puede tardar un tiempo.

Puede verificar el estado de los contenedores en ejecución con el comando:

docker compose ps                        # Muestra el estado de los contenedores en ejecución

Todos los contenedores (db, shlink, caddy) deben estar en estado running.

6. Verificación del funcionamiento

Después del inicio, es necesario asegurarse de que Shlink funciona correctamente.

• Verificación de Caddy: Abra su dominio (https://your-shlink-domain.com) en el navegador. Debería ver un mensaje de Shlink que dice "It works!" o la página del cliente web de Shlink, si lo ha desplegado. Si ve un error de certificado, es posible que el DNS aún no se haya actualizado o que haya un problema con el Caddyfile.
• Verificación de la API de Shlink: Realice una solicitud a la API de Shlink para asegurarse de que responde. Reemplace your-shlink-domain.com con su dominio.

curl -I https://your-shlink-domain.com/rest/v4/health

En la respuesta, debería ver el estado HTTP/2 200 y el encabezado server: Caddy, lo que indica un funcionamiento exitoso.

Si todo está en orden, ¡su Shlink está listo para usar! Puede empezar a acortar enlaces a través de la API o a través del cliente web oficial de Shlink, especificando la URL de su instancia de Shlink y la clave API.

Copias de seguridad y mantenimiento

La configuración de Shlink es solo el primer paso. Para garantizar la estabilidad y seguridad a largo plazo de su acortador de URL, las copias de seguridad regulares y el mantenimiento adecuado son cruciales.

1. Qué respaldar

Para Shlink, los siguientes componentes son críticamente importantes:

• Base de datos: Contiene todos los enlaces acortados, estadísticas de clics, dominios y configuraciones de Shlink. Este es el componente más importante.
• Archivos de configuración: Principalmente .env y Caddyfile. Estos definen cómo funcionan sus servicios.
• Datos de Caddy: El directorio shlink_caddy_data (de docker-compose.yml) contiene los certificados TLS de Let's Encrypt y otros datos de Caddy. Es importante conservarlo para evitar problemas al volver a obtener certificados después de una restauración.

2. Script simple de copia de seguridad automática

Crearemos un script simple que realizará un volcado de la base de datos y archivará los archivos importantes. Este script se puede ejecutar programado con cron.

Cree el archivo backup_shlink.sh en el directorio ~/shlink-docker:

nano ~/shlink-docker/backup_shlink.sh

Agregue el siguiente contenido (reemplace your_strong_db_root_password_here con su contraseña real de .env):

#!/bin/bash

# Directorio para copias de seguridad
BACKUP_DIR="/var/backups/shlink"
DATE=$(date +%Y-%m-%d_%H-%M-%S)
DB_CONTAINER_NAME="shlink-docker-db-1" # Nombre del contenedor de la base de datos (verifique con docker ps)
DB_NAME="shlink"
DB_USER="root"
DB_ROOT_PASSWORD="your_strong_db_root_password_here" # Use DB_ROOT_PASSWORD de .env

# Creamos el directorio para las copias de seguridad, si no existe
mkdir -p "$BACKUP_DIR"

echo "Iniciando copia de seguridad de Shlink en $DATE..."

# 1. Copia de seguridad de la base de datos
echo "Volcando la base de datos..."
docker exec "$DB_CONTAINER_NAME" mariadb-dump -u "$DB_USER" -p"$DB_ROOT_PASSWORD" "$DB_NAME" > "$BACKUP_DIR/$DB_NAME-$DATE.sql"
if [ $? -eq 0 ]; then
    echo "Volcado de la base de datos creado exitosamente: $BACKUP_DIR/$DB_NAME-$DATE.sql"
else
    echo "¡Error al crear el volcado de la base de datos!"
fi

# 2. Archivando archivos de configuración y datos de Caddy
echo "Archivando archivos de configuración y datos de Caddy..."
tar -czvf "$BACKUP_DIR/shlink-config-caddy-data-$DATE.tar.gz" -C ~/shlink-docker .env Caddyfile shlink_caddy_data
if [ $? -eq 0 ]; then
    echo "Archivo de configuración y datos de Caddy creado exitosamente: $BACKUP_DIR/shlink-config-caddy-data-$DATE.tar.gz"
else
    echo "¡Error al crear el archivo de configuración y datos de Caddy!"
fi

# 3. Eliminando copias de seguridad antiguas (más de 7 días)
echo "Eliminando copias de seguridad antiguas..."
find "$BACKUP_DIR" -type f -name "*.sql" -mtime +7 -delete
find "$BACKUP_DIR" -type f -name "*.tar.gz" -mtime +7 -delete
echo "Copias de seguridad antiguas eliminadas."

echo "Copia de seguridad de Shlink completada."

Haga el script ejecutable:

chmod +x ~/shlink-docker/backup_shlink.sh

3. Configuración de Cron para la copia de seguridad automática

Agregue el script a cron para su ejecución diaria. Por ejemplo, a las 03:00 de la madrugada.

crontab -e

Agregue la siguiente línea al final del archivo:

0 3 * * * /home/shlinkuser/shlink-docker/backup_shlink.sh >> /var/log/shlink_backup.log 2>&1

Esta línea ejecuta el script todos los días a las 3 de la madrugada y redirige su salida al archivo de registro /var/log/shlink_backup.log.

4. Dónde almacenar las copias de seguridad (almacenamiento externo)

Almacenar las copias de seguridad en el mismo servidor que el servicio principal es arriesgado. En caso de fallo del disco del VPS, perderá tanto el servicio como las copias de seguridad. Se recomienda utilizar almacenamiento externo:

• Almacenamiento de objetos en la nube (compatible con S3): AWS S3, Backblaze B2, DigitalOcean Spaces, MinIO. Estas son soluciones fiables y escalables. Puede usar utilidades como s3cmd o rclone para la sincronización automática de las copias de seguridad locales con la nube.
• VPS separado: Si tiene un segundo VPS, puede configurar rsync o scp para copiar las copias de seguridad a él.
• NAS/servidor local: Para uso personal, puede copiar las copias de seguridad a un dispositivo de almacenamiento en red doméstico.

Ejemplo de cómo agregar rclone para enviar copias de seguridad a un almacenamiento compatible con S3:

# Instalación de rclone
sudo apt install rclone -y

# Configuración de rclone (siga las instrucciones en pantalla, elija un proveedor compatible con S3)
rclone config

# Agregue al script backup_shlink.sh una línea para la sincronización después de crear el archivo:
# rclone sync "$BACKUP_DIR" "your_rclone_remote_name:your_bucket_name/shlink_backups"

5. Actualizaciones: rolling vs. ventana de mantenimiento

Las actualizaciones regulares son importantes para la seguridad y para obtener nuevas funciones.

• Actualización del SO: Ejecute sudo apt update && sudo apt upgrade -y cada pocas semanas o meses. Esto puede requerir un reinicio del servidor.
• Actualización de contenedores Docker:
  • Shlink: Para actualizar Shlink a una nueva versión, debe cambiar la etiqueta de la imagen en docker-compose.yml (por ejemplo, de shlinkio/shlink:4.0.0 a shlinkio/shlink:4.1.0).
  • Base de datos y Caddy: De manera similar, actualice las etiquetas de las imágenes de mariadb y caddy.

  Después de modificar docker-compose.yml, ejecute:

  
  cd ~/shlink-docker
  docker compose pull                         # Descarga las nuevas versiones de las imágenes
  docker compose up -d                        # Vuelve a crear los contenedores con las nuevas imágenes
  docker compose prune                        # Elimina las imágenes antiguas y no utilizadas
              

  Esto provocará una breve interrupción del servicio (unos segundos o minutos), por lo que es mejor realizarlo en una "ventana de mantenimiento" cuando el tráfico sea mínimo. ¡Siempre haga una copia de seguridad antes de actualizar!

Troubleshooting + FAQ

Durante la instalación y operación de Shlink pueden surgir varios problemas. Aquí cubriremos los más comunes y proporcionaremos recomendaciones para su solución.

¿Por qué mi dominio no funciona o Caddy no obtiene un certificado?

Este es uno de los problemas más frecuentes.

Qué verificar:

• Registros DNS: Asegúrese de que el registro A para su dominio (por ejemplo, s.example.com) esté configurado correctamente y apunte a la dirección IP de su VPS. Use dig your-shlink-domain.com en su máquina local para verificarlo. La propagación de DNS puede tardar hasta 24 horas, pero generalmente es más rápida.
• Puertos 80 y 443: Verifique que los puertos 80 (HTTP) y 443 (HTTPS) estén abiertos en su VPS. Caddy debe poder escuchar en estos puertos para obtener los certificados de Let's Encrypt. Use sudo ufw status o sudo ss -tulpn | grep -E ':(80|443)'. Asegúrese de que ningún otro servicio esté ocupando estos puertos.
• Caddyfile: Verifique la sintaxis de Caddyfile en busca de errores tipográficos. Asegúrese de que el dominio en Caddyfile coincida exactamente con el que está utilizando.
• Registros de Caddy: Verifique los registros del contenedor de Caddy en busca de errores: docker compose logs caddy. Busque mensajes de error al obtener certificados.

Cómo solucionarlo: Corrija el registro DNS, abra los puertos en el firewall, corrija Caddyfile y reinicie Caddy: docker compose restart caddy.

Shlink no acorta enlaces o arroja errores de API.

Si la interfaz web o la API de Shlink no funcionan correctamente, el problema podría estar en la configuración de Shlink o en la conexión a la base de datos.

Qué verificar:

• Registros de Shlink: Verifique los registros del contenedor de Shlink: docker compose logs shlink. Busque errores relacionados con la conexión a la base de datos o errores de la aplicación.
• Archivo .env: Asegúrese de que todas las variables de entorno, especialmente las relacionadas con la base de datos (DB_HOST, DB_USER, DB_PASSWORD, DB_NAME) y el dominio (DEFAULT_DOMAIN, API_KEY), estén configuradas correctamente y sean válidas.
• Disponibilidad de la base de datos: Asegúrese de que el contenedor de la base de datos (db) esté en funcionamiento: docker compose ps. Intente conectarse a la base de datos desde dentro del contenedor de Shlink: docker exec -it shlink-docker-shlink-1 mariadb -u shlink -p (ingrese la contraseña).

Cómo solucionarlo: Corrija los errores en .env o docker-compose.yml, luego reinicie los servicios: docker compose up -d --force-recreate shlink.

¿Qué configuración mínima de VPS es adecuada?

Para una instalación mínima de Shlink con Docker, base de datos y Caddy, necesitará un VPS con 1 vCPU, 1 GB de RAM y 20 GB de disco NVMe/SSD. Esto será suficiente para uso personal o un proyecto pequeño con una cantidad moderada de enlaces y tráfico. Sin embargo, para un funcionamiento más estable y la posibilidad de crecimiento, así como para un funcionamiento cómodo del SO y los servicios de Docker, se recomienda tener al menos 2 vCPU y 2-4 GB de RAM. Un disco NVMe/SSD mejorará significativamente el rendimiento de la base de datos. Se pueden considerar opciones de VPS con 2 vCPU y 4 GB de RAM, lo que proporcionará un buen equilibrio entre costo y rendimiento.

¿Qué elegir: VPS o dedicado para esta tarea?

Para la mayoría de los escenarios de uso de Shlink, un VPS (servidor privado virtual) es la opción óptima. Shlink en sí mismo no es una aplicación extremadamente intensiva en recursos, y los VPS modernos ofrecen suficiente rendimiento, flexibilidad y escalabilidad a un precio asequible. Un VPS es ideal para desarrolladores individuales, equipos pequeños, startups SaaS en etapas tempranas y proyectos personales. Un servidor dedicado solo es necesario en casos muy específicos: si espera cargas extremadamente altas (decenas de millones de clics al día), si requiere el máximo rendimiento de E/S para la base de datos, o si planea alojar en el mismo servidor muchas otras aplicaciones que consumen muchos recursos y que requieren un aislamiento completo del hardware. En la mayoría de los casos, pagar de más por un servidor dedicado para Shlink no tiene sentido.

¿Cómo actualizar Shlink u otros componentes?

La actualización de los componentes de Docker Compose se realiza cambiando la etiqueta de la imagen en el archivo docker-compose.yml a la nueva versión (por ejemplo, de shlinkio/shlink:4.0.0 a shlinkio/shlink:4.1.0) y luego ejecutando los comandos:

docker compose pull                 # Descarga las nuevas versiones de las imágenes
docker compose up -d                # Vuelve a crear los contenedores con las nuevas imágenes
docker image prune                  # Elimina las imágenes antiguas y no utilizadas
    

Antes de actualizar, siempre cree una copia de seguridad completa de la base de datos y los archivos de configuración. Las actualizaciones del SO se realizan mediante sudo apt update && sudo apt upgrade -y.

¿Puedo usar otro servidor web en lugar de Caddy (por ejemplo, Nginx)?

Sí, puede usar Nginx o cualquier otro proxy inverso. Para ello, deberá configurar Nginx manualmente para que proxy las solicitudes al contenedor de Shlink (normalmente al puerto interno 8080) y configurar por separado la obtención y renovación de certificados TLS (por ejemplo, con Certbot). Caddy fue elegido en esta guía por su simplicidad de configuración y su gestión automática de HTTPS, lo que simplifica significativamente el proceso para la mayoría de los usuarios.

¿Cómo obtener una clave de licencia GeoLite2?

Para obtener una clave de licencia GeoLite2, que Shlink utiliza para geoanálisis, debe registrarse en el sitio web de MaxMind. Después de registrarse, podrá generar su clave en la sección "My Account" -> "Manage License Keys". Inserte esta clave en la variable GEOLITE_LICENSE_KEY en el archivo .env.

Conclusiones y próximos pasos

¡Felicidades! Ha configurado y desplegado con éxito su propio acortador de URL Shlink en su VPS utilizando Docker. Ahora tiene una potente herramienta para la gestión de enlaces que le proporciona control total sobre sus datos, branding a través de su propio dominio y análisis detallado de clics. Esta experiencia no solo le ha proporcionado un servicio funcional, sino que también ha fortalecido sus habilidades en Docker, Linux y administración de servidores.

¿Qué sigue?

• Conexión del cliente web de Shlink: Despliegue el cliente web oficial de Shlink (Shlink Web Client) en un contenedor Docker separado o en otro subdominio. Esto le proporcionará una interfaz gráfica de usuario conveniente para gestionar enlaces sin necesidad de usar la API o la línea de comandos.
• Integración con otros servicios: Utilice la potente API de Shlink para integrar el acortamiento de enlaces en sus propias aplicaciones, sistemas CRM o scripts de automatización.
• Monitorización y registro: Configure una monitorización más avanzada de su VPS y contenedores Docker con herramientas como Prometheus/Grafana o ELK Stack para rastrear el rendimiento e identificar posibles problemas.
• Escalabilidad: Si su Shlink se vuelve muy popular, considere escalar la base de datos a un servidor separado o usar un clúster de Docker Swarm/Kubernetes para garantizar alta disponibilidad y manejar grandes cargas.