Встановлення Linkward

Конфігурація

Після запуску контейнерів Linkwarden необхідно налаштувати доступ до програми через ваш домен, забезпечити безпеку за допомогою HTTPS та виконати початкове налаштування. Ми будемо використовувати Caddy як зворотний проксі-сервер, оскільки він автоматично керує сертифікатами Let's Encrypt та спрощує налаштування HTTPS.

1. Налаштування DNS

Перед тим як приступити до налаштування Caddy, переконайтеся, що ваш домен або піддомен (наприклад, linkwarden.ВАШ_ДОМЕН.ru) вказує на IP-адресу вашого VPS. Додайте запис типу A в налаштуваннях DNS вашого доменного реєстратора:

Дайте час на розповсюдження DNS-записів (зазвичай від кількох хвилин до кількох годин).

2. Встановлення Caddy

Ми встановимо Caddy як окремий сервіс Docker, щоб він міг легко керувати HTTPS для Linkwarden.

Спочатку створіть директорію для конфігурації Caddy та його даних:

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

Створіть файл Caddyfile у директорії ~/linkwarden/caddy/config:

nano caddy/config/Caddyfile # Створити та відкрити Caddyfile

Вставте наступний вміст, замінивши linkwarden.ВАШ_ДОМЕН.ru на ваш фактичний домен:

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
    }
}

Збережіть файл (Ctrl+X, Y, Enter).

3. Додавання Caddy до Docker Compose

Тепер відредагуйте ваш файл ~/linkwarden/docker-compose.yml, щоб додати сервіс Caddy.

nano docker-compose.yml # Відкрити docker-compose.yml для редагування

Додайте наступну секцію caddy в кінець файлу, на тому ж рівні відступу, що й linkwarden та 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

Переконайтеся, що секція networks: для linkwarden та db також присутня і вказує на default (або на ім'я вашої мережі, якщо ви її визначили явно). Якщо у вас немає секції networks в кінці файлу, додайте її:

networks:
  default:
    external: false

Збережіть docker-compose.yml (Ctrl+X, Y, Enter).

4. Перезапуск Linkwarden з Caddy

Тепер оновіть стеки Docker Compose, щоб запустити Caddy.

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

Перевірте статус контейнерів:

docker compose ps # Переконайтеся, що caddy також запущено

Ви повинні побачити Up для linkwarden, db та caddy.

5. Перевірка працездатності

Відкрийте ваш браузер і перейдіть за адресою https://linkwarden.ВАШ_ДОМЕН.ru. Ви повинні побачити сторінку привітання Linkwarden. Caddy автоматично отримає та налаштує SSL-сертифікат від Let's Encrypt.

Якщо виникли проблеми, перевірте логи Caddy:

docker compose logs caddy # Переглянути логи Caddy для налагодження

При першому доступі до Linkwarden вам буде запропоновано створити обліковий запис адміністратора. Заповніть форму, використовуючи надійний пароль. Це буде ваш основний обліковий запис для керування закладками та користувачами.

6. Налаштування Linkwarden через веб-інтерфейс

Після створення облікового запису ви зможете увійти до Linkwarden. Вивчіть налаштування в розділі "Admin Settings", де можна налаштувати:

• User Management: Додавати нових користувачів, керувати їхніми ролями.
• Appearance: Змінити зовнішній вигляд.
• Integrations: Налаштувати інтеграції (наприклад, з RSS).
• Email Settings: Якщо ви налаштували SMTP в .env, тут можна перевірити та відправити тестовий лист.

Вітаємо! Ваш самокерований менеджер закладок Linkwarden повністю налаштований та захищений HTTPS.

Резервні копії та обслуговування

Регулярне резервне копіювання та своєчасне обслуговування є критично важливими для будь-якого production-сервісу. Linkwarden зберігає ваші цінні закладки та архіви, тому вкрай важливо забезпечити їх збереження.

1. Що резервувати

Для Linkwarden необхідно резервувати наступні компоненти:

• База даних PostgreSQL: Містить усі метадані закладок, теги, колекції, облікові записи користувачів. Це найважливіший компонент.
• Дані Linkwarden (linkwarden_data): Включає директорію з архівованими веб-сторінками, якщо ви використовуєте цю функцію.
• Конфігурація Caddy (caddy/config): Файл Caddyfile.
• Дані Caddy (caddy/data): Сертифікати Let's Encrypt. Хоча їх можна перевипустити, резервна копія прискорює відновлення.
• Файл .env Linkwarden: Містить секретний ключ та паролі.

2. Простий скрипт авторезервування

Створимо скрипт, який виконуватиме дамп бази даних та архівуватиме важливі файли. Ми використовуватимемо docker exec для роботи з базою даних всередині контейнера та tar для архівації.

Створіть директорію для скриптів резервного копіювання та сам скрипт:

mkdir -p ~/backups/linkwarden # Створити директорію для резервних копій
nano ~/backups/linkwarden/backup_linkwarden.sh # Створити скрипт резервного копіювання

Вставте наступний вміст у файл 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 "Резервне копіювання завершено."

Збережіть файл (Ctrl+X, Y, Enter) і зробіть його виконуваним:

chmod +x ~/backups/linkwarden/backup_linkwarden.sh # Зробити скрипт виконуваним

Перевірте ім'я контейнера бази даних командою docker ps і за необхідності змініть CONTAINER_NAME_DB у скрипті. Воно може бути linkwarden-db-1 або linkwarden_db_1 залежно від версії Docker Compose.

3. Автоматизація резервного копіювання за допомогою Cron

Налаштуйте Cron для щоденного запуску скрипта резервного копіювання. Відкрийте crontab вашого користувача:

crontab -e # Відкрити файл crontab для редагування

Додайте наступний рядок в кінець файлу, щоб скрипт запускався щодня о 03:00 ночі:

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

Збережіть та закрийте файл. Тепер ваші резервні копії створюватимуться автоматично.

4. Куди зберігати резервні копії

Зберігання резервних копій на тому ж сервері, що й основний сервіс, вкрай ризиковано. Якщо сервер вийде з ладу, ви втратите і сервіс, і резервні копії. Рекомендується використовувати зовнішні сховища:

• S3-сумісне сховище: Хмарні сервіси, такі як Amazon S3, DigitalOcean Spaces, Backblaze B2. Використовуйте rclone або awscli для автоматичного завантаження архівів після їх створення.
• Окремий VPS: Можна налаштувати інший, менш потужний VPS для зберігання резервних копій та використовувати rsync по SSH для їх синхронізації.
• NAS/локальне сховище: Якщо у вас є власне мережеве сховище, можна налаштувати VPN-тунель та передавати резервні копії туди.

Приклад додавання rclone до скрипта резервного копіювання (після створення архіву):

# --- Завантаження резервної копії в S3 (приклад з rclone) ---
# Переконайтеся, що rclone встановлено та налаштовано (rclone config)
# rclone copy "${BACKUP_FILE}" "s3remote:linkwarden-backups/"
# if [ $? -eq 0 ]; then
#     echo "Резервну копію успішно завантажено в S3."
# else
#     echo "Помилка при завантаженні резервної копії в S3."
# fi

5. Оновлення: rolling vs maintenance window

Підтримувати Linkwarden та сервер в актуальному стані критично важливо для безпеки та стабільності.

• Оновлення системи (Ubuntu): Рекомендується виконувати раз на місяць.

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

  Перезавантаження сервера (sudo reboot) може знадобитися після оновлення ядра або важливих системних компонентів. Плануйте це на час найменшого навантаження (maintenance window).

• Оновлення Docker-образів Linkwarden:

  Для оновлення Linkwarden до нової версії:

  
  cd ~/linkwarden # Перейти до директорії Linkwarden
  docker compose pull # Завантажити нові версії образів
  docker compose up -d # Перестворити контейнери з новими образами
              

  Рекомендується виконувати це в "вікно обслуговування", оскільки контейнери Linkwarden будуть перезапущені, що спричинить короткочасний простій сервісу.

• Оновлення Docker Engine: Виконується разом із системними оновленнями, якщо Docker встановлено з офіційного репозиторію.

Завжди робіть резервну копію перед великими оновленнями! Це ваша страховка на випадок непередбачених проблем.

Вирішення проблем + FAQ

Навіть при найретельнішому налаштуванні можуть виникнути проблеми. Цей розділ допоможе вам діагностувати та вирішити найпоширеніші з них.

Не можу отримати доступ до Linkwarden за доменом. Що робити?

Спочатку перевірте, чи правильно налаштовані DNS-записи. Використовуйте команду dig linkwarden.ВАШ_ДОМЕН.ru на локальній машині, щоб переконатися, що вона вказує на IP-адресу вашого VPS. Далі, перевірте, що Caddy запущений і не має помилок у логах: docker compose logs caddy. Переконайтеся, що порти 80 і 443 відкриті в брандмауері UFW на вашому VPS: sudo ufw status. Якщо Caddy не може отримати сертифікат, це може бути пов'язано з проблемами DNS або блокуванням портів.

Linkwarden не запускається після docker compose up -d.

Перевірте логи контейнера Linkwarden: docker compose logs linkwarden. Часті причини: некоректно налаштований файл .env (наприклад, відсутній SECRET_KEY або неправильний NEXTAUTH_URL), проблеми з підключенням до бази даних (перевірте логи контейнера db: docker compose logs db), або конфлікт портів, якщо ви вручну змінили docker-compose.yml і якийсь порт вже зайнятий.

Який VPS-конфіг мінімально підійде?

Для одного користувача або невеликої групи (до 5 осіб) з помірною кількістю закладок (до 1000) та нечастим використанням функції архівації сторінок, мінімально підійде VPS з 1 vCPU, 2 ГБ RAM та 40-60 ГБ SSD. Цього буде достатньо для стабільної роботи Linkwarden та його бази даних. Однак, якщо ви плануєте активно використовувати архівацію або масштабувати сервіс, рекомендується вибирати конфігурацію з 2 vCPU та 4 ГБ RAM.

Що вибрати — VPS чи dedicated для цього завдання?

Для більшості користувачів та невеликих команд VPS буде оптимальним вибором. Він пропонує достатню продуктивність, гнучкість та економічність. Dedicated сервер виправданий лише у випадках, коли Linkwarden використовуватиметься дуже великою організацією (сотні користувачів), потрібне зберігання терабайтів архівованих сторінок, або якщо на сервері працюватимуть інші вкрай ресурсомісткі програми, що вимагають ексклюзивного доступу до апаратних ресурсів. Dedicated сервери значно дорожчі та вимагають більшого досвіду в управлінні.

Як оновити Linkwarden до нової версії?

Для оновлення Linkwarden до нової версії достатньо перейти в директорію ~/linkwarden та виконати команди: docker compose pull (щоб завантажити нові образи) і потім docker compose up -d (щоб перестворити та запустити контейнери з новими образами). Завжди рекомендується зробити бекап перед оновленням. Також слідкуйте за офіційними релізами Linkwarden на GitHub щодо важливих змін або міграцій бази даних.

Чому Linkwarden повільно працює?

Причини повільної роботи можуть бути різними:

• Нестача ресурсів VPS: Перевірте завантаження CPU та RAM за допомогою htop. Якщо RAM постійно заповнена, або CPU працює на 100%, можливо, вам потрібен VPS з більшими ресурсами.
• Повільний диск: Якщо у вас HDD замість SSD, операції з базою даних та читання архівованих сторінок будуть повільними.
• Проблеми з базою даних: Перевірте логи db контейнера. Можливо, база даних потребує оптимізації, або відбувається занадто багато запитів.
• Проблеми з мережею: Якщо Linkwarden встановлений далеко від вас, або у вашого провайдера проблеми з мережею, це може викликати затримки.

Як скинути пароль адміністратора Linkwarden?

Якщо ви забули пароль адміністратора, його можна скинути через командний рядок. Спочатку отримайте оболонку всередині контейнера Linkwarden: docker exec -it linkwarden-linkwarden-1 bash (ім'я контейнера може відрізнятися, перевірте docker ps). Потім виконайте команду для скидання пароля (точна команда може змінюватися, перевірте документацію Linkwarden, але зазвичай це щось на зразок npm run cli user:reset-password -- -e [email protected] -p new_strong_password). Після скидання вийдіть з контейнера (exit).

Як налаштувати кастомний домен для Linkwarden, якщо я вже використовую Caddy для інших сервісів?

Якщо у вас вже є Caddy, що працює на хості, вам не потрібно запускати його в Docker Compose. Просто додайте нову секцію для linkwarden.ВАШ_ДОМЕН.ru у ваш існуючий Caddyfile на хості. Переконайтеся, що Linkwarden і Caddy можуть спілкуватися (наприклад, якщо Caddy на хості, а Linkwarden у Docker, вам потрібно буде відкрити порт Linkwarden або використовувати Docker-мережу). Приклад: reverse_proxy 172.17.0.X:3000, де 172.17.0.X - IP-адреса контейнера Linkwarden у Docker-мережі (можна дізнатися через docker inspect).

Висновки та наступні кроки

Ви успішно встановили та налаштували Linkwarden на вашому VPS, створивши надійний, приватний та повністю контрольований менеджер закладок. Тепер у вас є потужний інструмент для збереження, організації та архівування цінної веб-інформації, захищений HTTPS та з регулярними резервними копіями.

Куди рухатися далі?

• Запросіть користувачів: Якщо Linkwarden призначений для команди, запросіть колег та налаштуйте їхні облікові записи.
• Встановіть розширення для браузера: Скористайтеся офіційними розширеннями Linkwarden для Chrome, Firefox або Edge, щоб швидко зберігати посилання.
• Вивчіть додаткові функції: Ознайомтеся з можливостями Linkwarden, такими як RSS-імпорт, теги, колекції, функція "режим читання" та API для інтеграції з іншими сервісами.
• Моніторинг продуктивності: Налаштуйте систему моніторингу (наприклад, Prometheus + Grafana або Netdata) для відстеження ресурсів VPS та продуктивності Linkwarden.
• Масштабування: У міру зростання обсягу даних або кількості користувачів розгляньте можливість збільшення ресурсів VPS або оптимізації бази даних.