Instalación de Linkwarden

Configuración

Después de iniciar los contenedores de Linkwarden, es necesario configurar el acceso a la aplicación a través de su dominio, asegurar la conexión con HTTPS y realizar la configuración inicial. Utilizaremos Caddy como servidor proxy inverso, ya que gestiona automáticamente los certificados de Let's Encrypt y simplifica la configuración de HTTPS.

1. Configuración de DNS

Antes de proceder con la configuración de Caddy, asegúrese de que su dominio o subdominio (por ejemplo, linkwarden.SU_DOMINIO.ru) apunte a la dirección IP de su VPS. Agregue un registro de tipo A en la configuración DNS de su registrador de dominios:

Deje tiempo para que se propaguen los registros DNS (normalmente de unos minutos a varias horas).

2. Instalación de Caddy

Instalaremos Caddy como un servicio Docker separado para que pueda gestionar fácilmente HTTPS para Linkwarden.

Primero, cree un directorio para la configuración de Caddy y sus datos:

cd ~/linkwarden # Перейдите в директорию Linkwarden, если вы не там
mkdir caddy # Создать директорию для Caddy
mkdir caddy/data # Директория для данных Caddy (сертификаты)
mkdir caddy/config # Директория для конфигурации Caddy

Cree el archivo Caddyfile en el directorio ~/linkwarden/caddy/config:

nano caddy/config/Caddyfile # Создать и открыть Caddyfile

Pegue el siguiente contenido, reemplazando linkwarden.SU_DOMINIO.ru con su dominio real:

linkwarden.ВАШ_ДОМЕН.ru {
    # Проксировать все запросы к контейнеру Linkwarden
    reverse_proxy linkwarden:3000

    # Включить сжатие данных
    encode gzip zstd

    # Дополнительные заголовки безопасности (рекомендуется)
    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        X-Frame-Options "DENY"
        X-Content-Type-Options "nosniff"
        Referrer-Policy "strict-origin-when-cross-origin"
        Permissions-Policy "geolocation=(), microphone=(), camera=()"
    }

    # Логирование (опционально)
    log {
        output file /var/log/caddy/access.log
    }
}

Guarde el archivo (Ctrl+X, Y, Enter).

3. Añadir Caddy a Docker Compose

Ahora edite su archivo ~/linkwarden/docker-compose.yml para añadir el servicio Caddy.

nano docker-compose.yml # Открыть docker-compose.yml для редактирования

Añada la siguiente sección caddy al final del archivo, con el mismo nivel de indentación que linkwarden y db:

  caddy:
    image: caddy:2.7.6-alpine # Актуальная версия Caddy на 2026 год
    restart: unless-stopped
    ports:
      - "80:80" # Открыть порт 80 для Let's Encrypt HTTP-01 challenge
      - "443:443" # Открыть порт 443 для HTTPS
    volumes:
      - ./caddy/config/Caddyfile:/etc/caddy/Caddyfile # Маппинг вашего Caddyfile
      - ./caddy/data:/data # Маппинг для данных Caddy (сертификаты)
      - ./caddy/config:/config # Маппинг для конфигурации Caddy
      - ./caddy/logs:/var/log/caddy # Маппинг для логов Caddy (если включено логирование)
    networks:
      - default # Caddy должен быть в той же сети, что и Linkwarden

Asegúrese de que la sección networks: para linkwarden y db también esté presente y apunte a default (o al nombre de su red, si la definió explícitamente). Si no tiene una sección networks al final del archivo, añádala:

networks:
  default:
    external: false

Guarde docker-compose.yml (Ctrl+X, Y, Enter).

4. Reiniciar Linkwarden con Caddy

Ahora actualice las pilas de Docker Compose para iniciar Caddy.

docker compose down # Остановить и удалить существующие контейнеры Linkwarden (данные сохранятся в volumes)
docker compose up -d # Запустить все сервисы, включая Caddy

Verifique el estado de los contenedores:

docker compose ps # Убедитесь, что caddy также запущен

Debería ver Up para linkwarden, db y caddy.

5. Verificación de la funcionalidad

Abra su navegador y vaya a https://linkwarden.SU_DOMINIO.ru. Debería ver la página de bienvenida de Linkwarden. Caddy obtendrá y configurará automáticamente un certificado SSL de Let's Encrypt.

Si surgen problemas, revise los registros de Caddy:

docker compose logs caddy # Просмотреть логи Caddy для отладки

Al acceder a Linkwarden por primera vez, se le pedirá que cree una cuenta de administrador. Rellene el formulario utilizando una contraseña segura. Esta será su cuenta principal para gestionar marcadores y usuarios.

6. Configuración de Linkwarden a través de la interfaz web

Después de crear la cuenta, podrá iniciar sesión en Linkwarden. Explore la configuración en la sección "Admin Settings", donde puede configurar:

• User Management: Añadir nuevos usuarios, gestionar sus roles.
• Appearance: Cambiar la apariencia.
• Integrations: Configurar integraciones (por ejemplo, con RSS).
• Email Settings: Si ha configurado SMTP en .env, aquí puede probar y enviar un correo electrónico de prueba.

¡Felicidades! Su gestor de marcadores autoalojado Linkwarden está completamente configurado y protegido con HTTPS.

Copias de seguridad y mantenimiento

Las copias de seguridad regulares y el mantenimiento oportuno son cruciales para cualquier servicio en producción. Linkwarden almacena sus valiosos marcadores y archivos, por lo que es extremadamente importante asegurar su conservación.

1. Qué respaldar

Para Linkwarden, es necesario respaldar los siguientes componentes:

• Base de datos PostgreSQL: Contiene todos los metadatos de los marcadores, etiquetas, colecciones, cuentas de usuario. Este es el componente más importante.
• Datos de Linkwarden (linkwarden_data): Incluye el directorio con las páginas web archivadas, si utiliza esta función.
• Configuración de Caddy (caddy/config): El archivo Caddyfile.
• Datos de Caddy (caddy/data): Certificados de Let's Encrypt. Aunque se pueden volver a emitir, una copia de seguridad acelera la recuperación.
• Archivo .env de Linkwarden: Contiene la clave secreta y las contraseñas.

2. Script simple de copia de seguridad automática

Crearemos un script que realizará un volcado de la base de datos y archivará los archivos importantes. Utilizaremos docker exec para interactuar con la base de datos dentro del contenedor y tar para la compresión.

Cree un directorio para los scripts de copia de seguridad y el script en sí:

mkdir -p ~/backups/linkwarden # Создать директорию для бэкапов
nano ~/backups/linkwarden/backup_linkwarden.sh # Создать скрипт бэкапа

Pegue el siguiente contenido en el archivo backup_linkwarden.sh:

#!/bin/bash

# --- Конфигурация ---
BACKUP_DIR="/home/$USER/backups/linkwarden" # Директория для хранения бэкапов
LINKWARDEN_ROOT_DIR="/home/$USER/linkwarden" # Корневая директория Linkwarden
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="${BACKUP_DIR}/linkwarden_backup_${TIMESTAMP}.tar.gz"
DB_DUMP_FILE="linkwarden_db_dump_${TIMESTAMP}.sql"
CONTAINER_NAME_DB="linkwarden-db-1" # Имя контейнера базы данных (может отличаться, проверьте docker ps)
DB_USER="linkwardenuser" # Пользователь базы данных из вашего .env
DB_NAME="linkwarden" # Имя базы данных из вашего .env

# --- Создание дампа базы данных ---
echo "Создание дампа базы данных PostgreSQL..."
docker exec -t ${CONTAINER_NAME_DB} pg_dumpall -U ${DB_USER} > "${BACKUP_DIR}/${DB_DUMP_FILE}"
if [ $? -eq 0 ]; then
    echo "Дамп базы данных успешно создан: ${BACKUP_DIR}/${DB_DUMP_FILE}"
else
    echo "Ошибка при создании дампа базы данных."
    exit 1
fi

# --- Архивация данных Linkwarden, Caddy и конфигов ---
echo "Архивация данных Linkwarden, Caddy и конфигов..."
tar -czf "${BACKUP_FILE}" -C "${LINKWARDEN_ROOT_DIR}" \
    linkwarden_data \
    postgres_data \
    caddy/config/Caddyfile \
    caddy/data \
    .env \
    ${DB_DUMP_FILE} # Включаем дамп БД в общий архив

if [ $? -eq 0 ]; then
    echo "Архив успешно создан: ${BACKUP_FILE}"
else
    echo "Ошибка при создании архива."
    exit 1
fi

# --- Удаление временного дампа БД ---
rm "${BACKUP_DIR}/${DB_DUMP_FILE}"

# --- Очистка старых бэкапов (хранить последние 7 дней) ---
echo "Удаление старых бэкапов..."
find "${BACKUP_DIR}" -type f -name 'linkwarden_backup_*.tar.gz' -mtime +7 -delete
echo "Бэкапы старше 7 дней удалены."

echo "Резервное копирование завершено."

Guarde el archivo (Ctrl+X, Y, Enter) y hágalo ejecutable:

chmod +x ~/backups/linkwarden/backup_linkwarden.sh # Сделать скрипт исполняемым

Verifique el nombre del contenedor de la base de datos con el comando docker ps y, si es necesario, cambie CONTAINER_NAME_DB en el script. Podría ser linkwarden-db-1 o linkwarden_db_1 dependiendo de la versión de Docker Compose.

3. Automatización de copias de seguridad con Cron

Configure Cron para ejecutar el script de copia de seguridad diariamente. Abra el crontab de su usuario:

crontab -e # Открыть файл crontab для редактирования

Añada la siguiente línea al final del archivo para que el script se ejecute cada día a las 03:00 de la madrugada:

0 3 * * * /home/linkwardenuser/backups/linkwarden/backup_linkwarden.sh >> /home/linkwardenuser/backups/linkwarden/backup.log 2>&1

Guarde y cierre el archivo. Ahora sus copias de seguridad se crearán automáticamente.

4. Dónde almacenar las copias de seguridad

Almacenar las copias de seguridad en el mismo servidor que el servicio principal es extremadamente arriesgado. Si el servidor falla, perderá tanto el servicio como las copias de seguridad. Se recomienda utilizar almacenamiento externo:

• Almacenamiento compatible con S3: Servicios en la nube como Amazon S3, DigitalOcean Spaces, Backblaze B2. Utilice rclone o awscli para cargar automáticamente los archivos después de su creación.
• VPS separado: Puede configurar otro VPS menos potente para almacenar las copias de seguridad y utilizar rsync a través de SSH para sincronizarlas.
• NAS/Almacenamiento local: Si tiene su propio almacenamiento de red, puede configurar un túnel VPN y transferir las copias de seguridad allí.

Ejemplo de cómo añadir rclone al script de copia de seguridad (después de crear el archivo):

# --- Загрузка бэкапа в S3 (пример с rclone) ---
# Убедитесь, что rclone установлен и настроен (rclone config)
# rclone copy "${BACKUP_FILE}" "s3remote:linkwarden-backups/"
# if [ $? -eq 0 ]; then
#     echo "Бэкап успешно загружен в S3."
# else
#     echo "Ошибка при загрузке бэкапа в S3."
# fi

5. Actualizaciones: rolling vs ventana de mantenimiento

Mantener Linkwarden y el servidor actualizados es crucial para la seguridad y la estabilidad.

• Actualización del sistema (Ubuntu): Se recomienda realizarla una vez al mes.

  
  sudo apt update && sudo apt upgrade -y && sudo apt autoremove -y
              

  Puede ser necesario reiniciar el servidor (sudo reboot) después de actualizar el kernel o componentes importantes del sistema. Planifique esto para un momento de baja carga (ventana de mantenimiento).

• Actualización de imágenes Docker de Linkwarden:

  Para actualizar Linkwarden a una nueva versión:

  
  cd ~/linkwarden # Перейти в директорию Linkwarden
  docker compose pull # Загрузить новые версии образов
  docker compose up -d # Пересоздать контейнеры с новыми образами
              

  Se recomienda realizar esto en una "ventana de mantenimiento", ya que los contenedores de Linkwarden se reiniciarán, lo que provocará una breve interrupción del servicio.

• Actualización de Docker Engine: Se realiza junto con las actualizaciones del sistema, si Docker está instalado desde el repositorio oficial.

¡Siempre haga una copia de seguridad antes de las actualizaciones importantes! Es su seguro en caso de problemas imprevistos.

Solución de problemas + Preguntas frecuentes

Incluso con la configuración más cuidadosa, pueden surgir problemas. Esta sección le ayudará a diagnosticar y resolver los más comunes.

No puedo acceder a Linkwarden por dominio. ¿Qué hago?

Primero, verifique que los registros DNS estén configurados correctamente. Use el comando dig linkwarden.SU_DOMINIO.ru en su máquina local para asegurarse de que apunte a la dirección IP de su VPS. Luego, verifique que Caddy esté en ejecución y no tenga errores en los registros: docker compose logs caddy. Asegúrese de que los puertos 80 y 443 estén abiertos en el firewall UFW de su VPS: sudo ufw status. Si Caddy no puede obtener un certificado, esto podría deberse a problemas de DNS o al bloqueo de puertos.

Linkwarden no se inicia después de docker compose up -d.

Verifique los registros del contenedor Linkwarden: docker compose logs linkwarden. Las causas frecuentes son: un archivo .env configurado incorrectamente (por ejemplo, falta SECRET_KEY o NEXTAUTH_URL es incorrecto), problemas de conexión a la base de datos (verifique los registros del contenedor db: docker compose logs db), o un conflicto de puertos si modificó manualmente docker-compose.yml y algún puerto ya está ocupado.

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

Para un solo usuario o un grupo pequeño (hasta 5 personas) con una cantidad moderada de marcadores (hasta 1000) y un uso poco frecuente de la función de archivo de páginas, un VPS con 1 vCPU, 2 GB de RAM y 40-60 GB de SSD será mínimamente adecuado. Esto será suficiente para el funcionamiento estable de Linkwarden y su base de datos. Sin embargo, si planea usar activamente el archivo o escalar el servicio, se recomienda elegir una configuración con 2 vCPU y 4 GB de RAM.

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

Para la mayoría de los usuarios y equipos pequeños, un VPS será la opción óptima. Ofrece suficiente rendimiento, flexibilidad y rentabilidad. Un servidor dedicado solo se justifica en casos en los que Linkwarden será utilizado por una organización muy grande (cientos de usuarios), se requiere el almacenamiento de terabytes de páginas archivadas, o si en el servidor se ejecutarán otras aplicaciones extremadamente intensivas en recursos que requieran acceso exclusivo a los recursos de hardware. Los servidores dedicados son significativamente más caros y requieren más experiencia en gestión.

¿Cómo actualizar Linkwarden a una nueva versión?

Para actualizar Linkwarden a una nueva versión, simplemente vaya al directorio ~/linkwarden y ejecute los comandos: docker compose pull (para descargar las nuevas imágenes) y luego docker compose up -d (para recrear y ejecutar los contenedores con las nuevas imágenes). Siempre se recomienda hacer una copia de seguridad antes de actualizar. También esté atento a los lanzamientos oficiales de Linkwarden en GitHub para detectar cambios importantes o migraciones de bases de datos.

¿Por qué Linkwarden funciona lentamente?

Las razones del rendimiento lento pueden ser varias:

• Falta de recursos del VPS: Verifique la carga de CPU y RAM con htop. Si la RAM está constantemente llena o la CPU funciona al 100%, es posible que necesite un VPS con más recursos.
• Disco lento: Si tiene un HDD en lugar de un SSD, las operaciones de la base de datos y la lectura de páginas archivadas serán lentas.
• Problemas con la base de datos: Verifique los registros del contenedor db. Es posible que la base de datos necesite optimización o que se estén realizando demasiadas consultas.
• Problemas de red: Si Linkwarden está instalado lejos de usted, o su proveedor tiene problemas de red, esto puede causar retrasos.

¿Cómo restablecer la contraseña de administrador de Linkwarden?

Si olvidó la contraseña de administrador, puede restablecerla a través de la línea de comandos. Primero, obtenga un shell dentro del contenedor Linkwarden: docker exec -it linkwarden-linkwarden-1 bash (el nombre del contenedor puede variar, verifique docker ps). Luego, ejecute el comando para restablecer la contraseña (el comando exacto puede cambiar, verifique la documentación de Linkwarden, pero generalmente es algo como npm run cli user:reset-password -- -e [email protected] -p new_strong_password). Después de restablecer, salga del contenedor (exit).

¿Cómo configurar un dominio personalizado para Linkwarden si ya uso Caddy para otros servicios?

Si ya tiene Caddy funcionando en el host, no necesita ejecutarlo en Docker Compose. Simplemente agregue una nueva sección para linkwarden.SU_DOMINIO.ru en su Caddyfile existente en el host. Asegúrese de que Linkwarden y Caddy puedan comunicarse (por ejemplo, si Caddy está en el host y Linkwarden en Docker, deberá abrir el puerto de Linkwarden o usar la red de Docker). Ejemplo: reverse_proxy 172.17.0.X:3000, donde 172.17.0.X es la dirección IP del contenedor Linkwarden en la red de Docker (se puede averiguar con docker inspect).

Conclusiones y próximos pasos

Ha instalado y configurado Linkwarden con éxito en su VPS, creando un gestor de marcadores fiable, privado y totalmente controlado. Ahora tiene una potente herramienta para guardar, organizar y archivar información web valiosa, protegida con HTTPS y con copias de seguridad periódicas.

¿Qué sigue?

• Invite a usuarios: Si Linkwarden está destinado a un equipo, invite a sus colegas y configure sus cuentas.
• Instale extensiones del navegador: Utilice las extensiones oficiales de Linkwarden para Chrome, Firefox o Edge para guardar enlaces rápidamente.
• Explore funciones adicionales: Familiarícese con las capacidades de Linkwarden, como la importación RSS, etiquetas, colecciones, la función de "modo lector" y la API para la integración con otros servicios.
• Monitoreo del rendimiento: Configure un sistema de monitoreo (por ejemplo, Prometheus + Grafana o Netdata) para rastrear los recursos del VPS y el rendimiento de Linkwarden.
• Escalado: A medida que crezca el volumen de datos o el número de usuarios, considere aumentar los recursos del VPS u optimizar la base de datos.