Налаштування власного

Налаштування власного URL-скорочувача Shlink на VPS з Docker

TL;DR

У цьому детальному посібнику ми крок за кроком налаштуємо власний сервіс для скорочення URL-адрес Shlink на віртуальному приватному сервері (VPS) з використанням Docker та Docker Compose. Ви дізнаєтеся, як підготувати сервер, розгорнути Shlink разом з базою даних та веб-сервером Caddy для автоматичного отримання TLS-сертифікатів, а також як забезпечити резервне копіювання та обслуговування вашої установки.

Ви розгорнете Shlink – потужний та гнучкий URL-скорочувач з відкритим вихідним кодом.
Використаєте Docker та Docker Compose для легкої ізоляції та керування сервісами.
Налаштуєте автоматичне отримання HTTPS-сертифікатів за допомогою Caddy.
Отримаєте повний контроль над вашими скороченими посиланнями та їх аналітикою.
Освоїте базові принципи обслуговування та резервного копіювання Docker-додатків.
Створите відмовостійке та безпечне середовище для вашого сервісу.

Що ми налаштовуємо і навіщо

В епоху, коли кожен символ має значення, а довгі, незграбні URL-адреси можуть відштовхнути користувачів та зіпсувати зовнішній вигляд повідомлення, сервіси для скорочення посилань стали незамінним інструментом. Shlink – це саморозміщуване (self-hosted) рішення з відкритим вихідним кодом, яке дозволяє вам створити власний, повністю контрольований сервіс для скорочення URL-адрес. На відміну від популярних комерційних аналогів, таких як Bitly або Rebrandly, Shlink надає вам повну свободу та володіння даними, а також можливість використовувати власні домени для брендування посилань.

У підсумку цього посібника ви отримаєте повністю функціонуючий URL-скорочувач Shlink, розгорнутий на вашому власному VPS. Це означає, що ви зможете створювати короткі, запам'ятовувані посилання, які вказуватимуть на ваш домен (наприклад, my.link/abc замість long-and-ugly-url.com/some/path/to/resource). Крім базового скорочення, Shlink пропонує багатий набір функцій: детальну аналітику переходів (кількість кліків, географія, браузери, ОС), створення QR-кодів для кожного посилання, можливість встановлення паролів на посилання, лімітів переходів та термінів дії, а також потужний API для інтеграції з іншими вашими сервісами. Ви зможете керувати всіма цими функціями через зручний веб-інтерфейс або командний рядок.

Чому self-hosted на VPS, а не хмарні керовані сервіси? Вибір на користь власного VPS зумовлений кількома ключовими перевагами. По-перше, це повний контроль над даними. Вся інформація про ваші посилання та їх аналітику зберігається на вашому сервері, а не на серверах стороннього провайдера. Це критично для проєктів, що вимагають підвищеної конфіденційності або відповідності суворим регуляторним вимогам. По-друге, це кастомізація. Ви можете налаштувати Shlink під свої потреби, інтегрувати його з іншими інструментами, використовувати власний брендований домен без обмежень, які часто накладають безкоштовні тарифи хмарних сервісів. По-третє, це економія в довгостроковій перспективі. Хоча оренда VPS вимагає деяких початкових вкладень та часу на налаштування, для високонавантажених або довгострокових проєктів це часто виявляється значно дешевше, ніж щомісячні підписки на комерційні сервіси, особливо при великому обсязі посилань або аналітики. Нарешті, це чудовий спосіб поглибити свої знання в галузі адміністрування серверів та роботи з Docker, що є цінним навичком для будь-якого розробника або технічного спеціаліста.

Альтернативи Shlink включають безліч комерційних рішень, таких як Bitly, Rebrandly, Short.io, TinyURL, а також інші self-hosted варіанти, наприклад, Kutt або Polr. Однак Shlink виділяється своєю зрілістю, активним розвитком, багатим функціоналом та підтримкою Docker, що робить його ідеальним вибором для розгортання на VPS.

Який VPS-конфіг потрібен для цього завдання

Для розгортання Shlink з Docker та базою даних на VPS, важливо вибрати відповідні апаратні ресурси. Shlink сам по собі досить легковажний, але Docker, база даних (наприклад, MariaDB або PostgreSQL) та веб-сервер (Caddy) вимагають певного мінімуму.

Мінімальні вимоги:

CPU: 1 vCPU (віртуальне ядро). Для невеликих проєктів та тестування цього буде достатньо.
RAM: 1 GB. Це абсолютний мінімум. Docker Engine, ОС та база даних споживають значну частину цієї пам'яті, залишаючи мало для самого Shlink. Можуть виникати проблеми при пікових навантаженнях або під час оновлень.
Диск: 20 GB NVMe/SSD. NVMe або SSD вкрай бажані для продуктивності бази даних. 20 GB вистачить для ОС, Docker-образів, даних Shlink та логів.
Мережа: 100 Mbps з необмеженим трафіком або з великим запасом (від 1 TB на місяць). Shlink не є сильно мережезалежним сервісом, якщо тільки ви не очікуєте мільйони кліків на день.

Коли потрібен dedicated, а не VPS:

Dedicated сервер (виділений сервер) стає необхідним, коли ваш URL-скорочувач починає обробляти дуже великі обсяги трафіку (десятки або сотні мільйонів кліків на місяць), коли потрібна максимальна продуктивність бази даних, або якщо ви плануєте розміщувати на цьому ж сервері безліч інших ресурсоємних додатків. Також dedicated сервери пропонують вищий рівень ізоляції та часто ширші можливості щодо кастомізації апаратної частини. Для Shlink це зазвичай не потрібно, якщо тільки ви не будуєте глобальний сервіс з мільярдами переходів.

Локація: на що впливає

Затримка (latency): Чим ближче сервер до вашої основної аудиторії або до серверів, на які вказуватимуть скорочені посилання, тим меншою буде затримка при переході. Для URL-скорочувача це не критично, оскільки сам редирект відбувається дуже швидко, але для загальної чутливості адмін-панелі та API це може бути помітно.
Законодавство: Залежно від того, де фізично розташований сервер, на нього поширюються закони цієї країни щодо зберігання даних, конфіденційності тощо. Переконайтеся, що обрана юрисдикція відповідає вашим вимогам.
Доступність: Деякі регіони можуть пропонувати більш стабільне та швидке мережеве з'єднання, а також кращу зв'язність з різними частинами світу.

Зазвичай рекомендується вибирати локацію, яка географічно близька до вашої цільової аудиторії або до вас самих, щоб спростити керування.

Підготовка сервера

Після отримання доступу до вашого нового VPS, насамперед необхідно провести мінімальне налаштування для забезпечення безпеки та зручності роботи. Ми будемо використовувати дистрибутив Ubuntu Server 24.04 LTS (актуальна версія на 2026 рік) як найбільш поширений і добре задокументований вибір.

1. Підключення по SSH

Підключіться до сервера як користувач root (або той користувач, якого надав хостинг-провайдер) по SSH. Замініть на IP-адресу вашого сервера.


ssh root@

Якщо ви використовуєте пароль, система запитає його. Якщо ви використовуєте SSH-ключі, переконайтеся, що ваш публічний ключ додано на сервер.

2. Оновлення системи

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


sudo apt update          # Оновлюємо список доступних пакетів
sudo apt upgrade -y      # Встановлюємо всі доступні оновлення без підтвердження
sudo apt autoremove -y   # Видаляємо непотрібні пакети

3. Створення нового користувача з правами sudo

Працювати під користувачем root небезпечно. Створіть нового користувача та надайте йому права sudo.


sudo adduser shlinkuser                  # Створюємо нового користувача з іменем shlinkuser
sudo usermod -aG sudo shlinkuser         # Додаємо користувача shlinkuser до групи sudo

Після створення користувача, задайте йому надійний пароль. Тепер ви можете вийти з root і увійти під новим користувачем:


exit                                     # Виходимо з root
ssh shlinkuser@             # Входимо під новим користувачем

4. Налаштування SSH-ключів для нового користувача (рекомендується)

Для підвищення безпеки та зручності, налаштуйте вхід за SSH-ключами для shlinkuser. Якщо у вас ще немає SSH-ключа на локальній машині, створіть його:


ssh-keygen -t rsa -b 4096 -C "[email protected]" # Створюємо новий SSH-ключ (на вашій локальній машині)

Потім скопіюйте публічний ключ на сервер:


ssh-copy-id shlinkuser@     # Копіюємо публічний ключ на сервер

Або вручну додайте вміст файлу ~/.ssh/id_rsa.pub (на локальній машині) до файлу ~/.ssh/authorized_keys на сервері (для користувача shlinkuser).

Після цього можна відключити вхід за паролем для SSH, відредагувавши файл /etc/ssh/sshd_config. Знайдіть рядки:


PasswordAuthentication yes

І змініть її на:


PasswordAuthentication no

Також рекомендується відключити вхід для користувача root по SSH, змінивши:


PermitRootLogin yes

на:


PermitRootLogin no

Після змін перезапустіть SSH-сервіс:


sudo systemctl restart sshd

Важливо: Переконайтеся, що ви можете увійти за SSH-ключем, перш ніж відключати вхід за паролем! Інакше ви можете втратити доступ до сервера.

5. Встановлення та налаштування брандмауера UFW

Брандмауер Uncomplicated Firewall (UFW) простий у налаштуванні та значно підвищує безпеку сервера, блокуючи небажані вхідні з'єднання.


sudo apt install ufw -y                 # Встановлюємо UFW
sudo ufw allow OpenSSH                  # Дозволяємо SSH-з'єднання (порт 22)
sudo ufw allow http                     # Дозволяємо HTTP-з'єднання (порт 80)
sudo ufw allow https                    # Дозволяємо HTTPS-з'єднання (порт 443)
sudo ufw enable                         # Вмикаємо UFW
sudo ufw status                         # Перевіряємо статус UFW

Вивід sudo ufw status повинен показати, що SSH, HTTP та HTTPS дозволені.

6. Встановлення Fail2Ban

Fail2Ban сканує логи сервера (наприклад, SSH, веб-сервера) на предмет підозрілої активності (численні невдалі спроби входу) та тимчасово або назавжди блокує IP-адреси зловмисників.


sudo apt install fail2ban -y            # Встановлюємо Fail2Ban
sudo systemctl enable fail2ban          # Вмикаємо автозапуск Fail2Ban при старті системи
sudo systemctl start fail2ban           # Запускаємо сервіс Fail2Ban
sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local # Копіюємо конфіг для локальних змін

Ви можете відредагувати /etc/fail2ban/jail.local для тонкого налаштування, наприклад, змінити bantime (час блокування) або findtime (період, за який рахуються невдалі спроби). За замовчуванням, SSH вже захищений.

Встановлення ПЗ — покроково

Тепер, коли сервер підготовлений, перейдемо до встановлення необхідного програмного забезпечення: Docker Engine та Docker Compose. Ми будемо використовувати актуальні версії, доступні у 2026 році.

1. Встановлення Docker Engine

Docker Engine – це основна платформа для запуску контейнерів. Ми будемо встановлювати його з офіційного репозиторію Docker, щоб завжди мати найсвіжіші версії.


# Оновлюємо список пакетів та встановлюємо залежності для apt
sudo apt update
sudo apt install ca-certificates curl gnupg lsb-release -y

# Додаємо офіційний GPG-ключ 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

# Додаємо репозиторій Docker до 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

# Оновлюємо список пакетів apt після додавання репозиторію Docker
sudo apt update

# Встановлюємо Docker Engine, Docker CLI та containerd.io
# Актуальні версії на 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

# Перевіряємо, що Docker встановлено та запущено
sudo systemctl status docker

Вивід sudo systemctl status docker повинен показати, що Docker активний (active (running)).

2. Додавання користувача до групи Docker

Щоб уникнути постійного використання sudo при роботі з Docker, додайте вашого користувача до групи docker.


sudo usermod -aG docker shlinkuser       # Додаємо shlinkuser до групи docker
newgrp docker                            # Активуємо зміни для поточної сесії

Тепер ви можете перевірити встановлення Docker без sudo:


docker run hello-world                   # Запускаємо тестовий контейнер 'hello-world'

Якщо ви бачите вітальне повідомлення від Docker, значить, все налаштовано правильно.

3. Створення каталогу для проєкту Shlink

Створимо директорію, де зберігатимуться всі файли проєкту Shlink.


mkdir ~/shlink-docker                    # Створюємо директорію shlink-docker у домашньому каталозі користувача
cd ~/shlink-docker                       # Переходимо до створеної директорії

4. Завантаження файлу Docker Compose для Shlink

Shlink надає офіційний файл docker-compose.yml, який включає всі необхідні сервіси: сам Shlink, базу даних (MariaDB за замовчуванням) та веб-сервер Caddy для зворотного проксі та HTTPS. Ми будемо використовувати його як основу.

На 2026 рік офіційні образи Shlink та Caddy активно підтримуються. Shlink версії 4.x та Caddy версії 2.x.


# Завантажуємо офіційний docker-compose.yml файл
curl -sL https://raw.githubusercontent.com/shlinkio/shlink-web-client/master/docker/docker-compose.yml -o docker-compose.yml

# Завантажуємо приклад файлу .env
curl -sL https://raw.githubusercontent.com/shlinkio/shlink-web-client/master/docker/.env.example -o .env

# Завантажуємо приклад Caddyfile
curl -sL https://raw.githubusercontent.com/shlinkio/shlink-web-client/master/docker/Caddyfile -o Caddyfile

Тепер у вас є три ключові файли в директорії ~/shlink-docker: docker-compose.yml, .env та Caddyfile. Ми будемо їх редагувати на наступному етапі.

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

Після завантаження базових файлів, необхідно їх налаштувати під ваше середовище. Це включає в себе змінні оточення, налаштування бази даних, конфігурацію веб-сервера Caddy та DNS-записи.

1. Налаштування файлу `.env`

Файл .env містить змінні оточення, які використовуються Docker Compose для налаштування сервісів. Відредагуйте його, замінивши заповнювачі на ваші значення. Відкрийте файл для редагування:


nano .env

Приклад вмісту .env (обов'язково змініть DB_ROOT_PASSWORD, DB_PASSWORD, DEFAULT_DOMAIN та 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 # Обов'язково змініть!
DB_ROOT_PASSWORD=your_strong_db_root_password_here # Обов'язково змініть!

# Shlink configuration
DEFAULT_DOMAIN=your-shlink-domain.com # Замініть на ваш домен (наприклад, s.example.com)
DEFAULT_BASE_URL=https://your-shlink-domain.com # Замініть на ваш домен
DEFAULT_TITLE=My Custom Shlink
GEOLITE_LICENSE_KEY=your_geolite_license_key # Необов'язково, для гео-аналітики. Отримати на MaxMind.
API_KEY=your_shlink_api_key_here # Обов'язково згенеруйте та змініть!
INITIAL_API_KEY=your_initial_api_key_for_first_login # Необов'язково, для першого входу в адмінку
SHLINK_WEB_CLIENT_URL=https://shlink-web.your-shlink-domain.com # URL для веб-клієнта, якщо розгортаєте його окремо

Пояснення:

DB_PASSWORD та DB_ROOT_PASSWORD: Дуже важливо використовувати унікальні та надійні паролі.
DEFAULT_DOMAIN: Це домен, який буде використовуватися для скорочених посилань. Наприклад, якщо ви хочете, щоб посилання виглядали як s.example.com/xyz, то тут має бути s.example.com. Переконайтеся, що цей домен (або піддомен) вказує на IP-адресу вашого VPS.
API_KEY: Згенеруйте довгий, випадковий ключ. Він буде використовуватися для автентифікації при доступі до API Shlink та у веб-клієнті.
GEOLITE_LICENSE_KEY: Якщо ви хочете використовувати геоаналітику, вам потрібно отримати безкоштовний ключ ліцензії GeoLite2 від MaxMind (потрібна реєстрація). Без нього геоаналітика не працюватиме.

2. Налаштування файлу `Caddyfile`

Caddy виступатиме в ролі зворотного проксі, перенаправляючи запити до Shlink та автоматично керуючи HTTPS-сертифікатами через Let's Encrypt. Відкрийте файл для редагування:


nano Caddyfile

Замініть your-shlink-domain.com на ваш домен (той самий, що й у .env).


{
  email [email protected] # Замініть на ваш email для сповіщень Let's Encrypt
}

your-shlink-domain.com { # Замініть на ваш домен (наприклад, s.example.com)
  reverse_proxy shlink:8080
}

# Якщо ви розгортаєте веб-клієнт Shlink окремо, додайте секцію для нього:
# shlink-web.your-shlink-domain.com { # Замініть на ваш домен для веб-клієнта
#   root * /app/dist
#   file_server
#   try_files {path} {path}/ /index.html
# }

Пояснення:

email [email protected]: Вкажіть вашу дійсну адресу електронної пошти. Let's Encrypt використовуватиме її для сповіщень про сертифікати.
your-shlink-domain.com: Це домен, за яким буде доступний ваш Shlink. Caddy автоматично отримає для нього HTTPS-сертифікат.
shlink:8080: Це внутрішнє ім'я сервісу Shlink всередині Docker Compose та його порт.
(Опціонально) Якщо ви розгортаєте веб-клієнт Shlink (shlink-web-client) у тому ж Docker Compose, вам може знадобитися окрема секція для нього, як показано в закоментованому прикладі. У цьому посібнику ми фокусуємося на самому Shlink, а веб-клієнт можна підключити пізніше через API.

3. Налаштування файлу `docker-compose.yml` (за необхідності)

Зазвичай завантажений docker-compose.yml підходить без змін, але варто його перевірити. Він визначає три сервіси:

db: База даних (MariaDB).
shlink: Сам сервіс Shlink.
caddy: Веб-сервер/зворотний проксі.

Переконайтеся, що версії образів актуальні (наприклад, shlinkio/shlink:4.0.0, mariadb:11.3, caddy:2.7-alpine на 2026 рік). Якщо ви плануєте використовувати PostgreSQL, вам потрібно буде змінити образ db та відповідні змінні в .env.


# Приклад docker-compose.yml (скорочено)
version: '3.8'

services:
  db:
    image: mariadb:11.3 # Актуальна версія MariaDB на 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 # Актуальна версія Shlink на 2026 рік
    restart: unless-stopped
    env_file:
      - .env
    ports:
      - "8080:8080" # Внутрішній порт 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 # Актуальна версія Caddy на 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. Налаштування DNS-записів

Перш ніж запускати Shlink, необхідно переконатися, що ваш домен (або піддомен, наприклад, s.example.com) вказує на IP-адресу вашого VPS. Перейдіть до панелі керування вашого доменного реєстратора (або провайдера DNS) і створіть A-запис:

Тип: A
Ім'я/Хост: ваш піддомен (наприклад, s, якщо повний домен s.example.com) або @, якщо ви використовуєте основний домен.
Значення/IP-адреса: IP-адреса вашого VPS.

Поширення DNS-записів може зайняти від кількох хвилин до кількох годин. Ви можете перевірити статус за допомогою команди dig на локальній машині:


dig +short your-shlink-domain.com

Вона повинна повернути IP-адресу вашого VPS.

5. Запуск Shlink за допомогою Docker Compose

Після всіх налаштувань, перебуваючи в директорії ~/shlink-docker, запустіть усі сервіси:


docker compose up -d                     # Запускаємо контейнери у фоновому режимі

Це завантажить необхідні Docker-образи (якщо їх немає локально), створить контейнери, налаштує мережу та запустить сервіси. Перший запуск може зайняти деякий час.

Перевірити статус запущених контейнерів можна командою:


docker compose ps                        # Показує статус запущених контейнерів

Усі контейнери (db, shlink, caddy) повинні бути в статусі running.

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

Після запуску необхідно переконатися, що Shlink працює коректно.

Перевірка Caddy: Відкрийте в браузері ваш домен (https://your-shlink-domain.com). Ви повинні побачити повідомлення від Shlink про те, що "It works!" або сторінку веб-клієнта Shlink, якщо ви його розгорнули. Якщо ви бачите помилку сертифіката, можливо, DNS ще не оновився або є проблема з Caddyfile.
Перевірка API Shlink: Виконайте запит до API Shlink, щоб переконатися, що він відповідає. Замініть your-shlink-domain.com на ваш домен.


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

У відповіді ви повинні побачити статус HTTP/2 200 та заголовок server: Caddy, що вказує на успішну роботу.

Якщо все гаразд, ваш Shlink готовий до використання! Ви можете почати скорочувати посилання через API або через офіційний веб-клієнт Shlink, вказавши URL вашого Shlink-інстансу та API-ключ.

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

Налаштування Shlink – це лише перший крок. Для забезпечення довгострокової стабільності та безпеки вашого скорочувача URL-адрес вкрай важливі регулярні резервні копії та правильне обслуговування.

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

Для Shlink критично важливі наступні компоненти:

База даних: Містить усі скорочені посилання, статистику переходів, домени та налаштування Shlink. Це найважливіший компонент.
Конфігураційні файли: В першу чергу це .env та Caddyfile. Вони визначають, як працюють ваші сервіси.
Дані Caddy: Каталог shlink_caddy_data (з docker-compose.yml) містить TLS-сертифікати Let's Encrypt та інші дані Caddy. Важливо зберігати його, щоб уникнути проблем з повторним отриманням сертифікатів після відновлення.

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

Ми створимо простий скрипт, який буде виконувати дамп бази даних та архівувати важливі файли. Цей скрипт можна запускати за розкладом за допомогою cron.

Створіть файл backup_shlink.sh у директорії ~/shlink-docker:


nano ~/shlink-docker/backup_shlink.sh

Додайте наступний вміст (замініть your_strong_db_root_password_here на ваш реальний пароль з .env):


#!/bin/bash

# Каталог для резервних копій
BACKUP_DIR="/var/backups/shlink"
DATE=$(date +%Y-%m-%d_%H-%M-%S)
DB_CONTAINER_NAME="shlink-docker-db-1" # Ім'я контейнера бази даних (перевірте через docker ps)
DB_NAME="shlink"
DB_USER="root"
DB_ROOT_PASSWORD="your_strong_db_root_password_here" # Використовуйте DB_ROOT_PASSWORD з .env

# Створюємо директорію для резервних копій, якщо її немає
mkdir -p "$BACKUP_DIR"

echo "Починаємо резервне копіювання Shlink о $DATE..."

# 1. Резервне копіювання бази даних
echo "Дамп бази даних..."
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 "Дамп бази даних успішно створено: $BACKUP_DIR/$DB_NAME-$DATE.sql"
else
    echo "Помилка при створенні дампу бази даних!"
fi

# 2. Архівування конфігураційних файлів та даних Caddy
echo "Архівування конфігураційних файлів та даних 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 "Архів конфігурації та даних Caddy успішно створено: $BACKUP_DIR/shlink-config-caddy-data-$DATE.tar.gz"
else
    echo "Помилка при створенні архіву конфігурації та даних Caddy!"
fi

# 3. Видалення старих резервних копій (старше 7 днів)
echo "Видалення старих резервних копій..."
find "$BACKUP_DIR" -type f -name "*.sql" -mtime +7 -delete
find "$BACKUP_DIR" -type f -name "*.tar.gz" -mtime +7 -delete
echo "Старі резервні копії видалено."

echo "Резервне копіювання Shlink завершено."

Зробіть скрипт виконуваним:


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

3. Налаштування Cron для автоматичного резервного копіювання

Додайте скрипт до cron для щоденного виконання. Наприклад, о 03:00 ночі.


crontab -e

Додайте наступну строку в кінець файлу:


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

Цей рядок запускає скрипт щодня о 3 годині ночі та перенаправляє його вивід у лог-файл /var/log/shlink_backup.log.

4. Куди зберігати резервні копії (зовнішнє сховище)

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

Хмарне сховище об'єктів (S3-сумісне): AWS S3, Backblaze B2, DigitalOcean Spaces, MinIO. Це надійні та масштабовані рішення. Ви можете використовувати утиліти на кшталт s3cmd або rclone для автоматичної синхронізації локальних резервних копій з хмарою.
Окремий VPS: Якщо у вас є другий VPS, ви можете налаштувати rsync або scp для копіювання резервних копій на нього.
Локальний NAS/сервер: Для особистого використання можна копіювати резервні копії на домашній мережевий накопичувач.

Приклад додавання rclone для відправки резервних копій на S3-сумісне сховище:


# Встановлення rclone
sudo apt install rclone -y

# Налаштування rclone (дотримуйтесь інструкцій на екрані, виберіть S3-сумісний провайдер)
rclone config

# Додайте до скрипта backup_shlink.sh рядок для синхронізації після створення архіву:
# rclone sync "$BACKUP_DIR" "your_rclone_remote_name:your_bucket_name/shlink_backups"

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

Регулярні оновлення важливі для безпеки та отримання нових функцій.

Оновлення ОС: Виконуйте sudo apt update && sudo apt upgrade -y раз на кілька тижнів або місяців. Для цього може знадобитися перезавантаження сервера.
Оновлення Docker-контейнерів:
- Shlink: Щоб оновити Shlink до нової версії, вам потрібно змінити тег образу в docker-compose.yml (наприклад, з shlinkio/shlink:4.0.0 на shlinkio/shlink:4.1.0).
- База даних та Caddy: Аналогічно, оновіть теги образів mariadb та caddy.
Після зміни docker-compose.yml виконайте:
```
cd ~/shlink-docker
docker compose pull                         # Завантажує нові версії образів
docker compose up -d                        # Перестворює контейнери з новими образами
docker compose prune                        # Видаляє старі, невикористовувані образи
            
```
Це призведе до короткочасного простою сервісу (кілька секунд або хвилин), тому краще виконувати у "вікно обслуговування" (maintenance window), коли трафік мінімальний. Перед оновленням завжди робіть резервну копію!

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

У процесі встановлення та експлуатації Shlink можуть виникнути різні проблеми. Тут ми розглянемо найпоширеніші з них та надамо рекомендації щодо їх усунення.

Чому мій домен не працює або Caddy не отримує сертифікат?

Це одна з найчастіших проблем.

Що перевірити:

DNS-записи: Переконайтеся, що A-запис для вашого домену (наприклад, s.example.com) правильно налаштований і вказує на IP-адресу вашого VPS. Використовуйте dig your-shlink-domain.com на локальній машині, щоб перевірити це. Розповсюдження DNS може зайняти до 24 годин, але зазвичай відбувається швидше.
Порти 80 та 443: Перевірте, що порти 80 (HTTP) та 443 (HTTPS) відкриті на вашому VPS. Caddy повинен мати можливість слухати ці порти для отримання сертифікатів Let's Encrypt. Використовуйте sudo ufw status або sudo ss -tulpn | grep -E ':(80|443)'. Переконайтеся, що жоден інший сервіс не займає ці порти.
Caddyfile: Перевірте синтаксис Caddyfile на наявність друкарських помилок. Переконайтеся, що домен у Caddyfile точно збігається з тим, який ви використовуєте.
Логи Caddy: Перевірте логи контейнера Caddy на наявність помилок: docker compose logs caddy. Шукайте повідомлення про помилки при отриманні сертифікатів.

Як виправити: Виправте DNS-запис, відкрийте порти у брандмауері, виправте Caddyfile та перезапустіть Caddy: docker compose restart caddy.

Shlink не скорочує посилання або видає помилки API.

Якщо веб-інтерфейс або API Shlink не працюють належним чином, проблема може бути в конфігурації Shlink або підключенні до бази даних.

Що перевірити:

Логи Shlink: Перевірте логи контейнера Shlink: docker compose logs shlink. Шукайте помилки, пов'язані з підключенням до бази даних або помилками програми.
Файл .env: Переконайтеся, що всі змінні оточення, особливо пов'язані з базою даних (DB_HOST, DB_USER, DB_PASSWORD, DB_NAME) та доменом (DEFAULT_DOMAIN, API_KEY), налаштовані правильно та відповідають дійсності.
Доступність бази даних: Переконайтеся, що контейнер бази даних (db) запущений і працює: docker compose ps. Спробуйте підключитися до бази даних зсередини контейнера Shlink: docker exec -it shlink-docker-shlink-1 mariadb -u shlink -p (введіть пароль).

Як виправити: Виправте помилки в .env або docker-compose.yml, потім перезапустіть сервіси: docker compose up -d --force-recreate shlink.

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

Для мінімальної установки Shlink з Docker, базою даних та Caddy, вам знадобиться VPS з 1 vCPU, 1 GB RAM та 20 GB NVMe/SSD диска. Цього буде достатньо для особистого використання або невеликого проєкту з помірною кількістю посилань та трафіку. Однак, для більш стабільної роботи та можливості зростання, а також для комфортної роботи ОС та Docker-сервісів, рекомендується мати не менше 2 vCPU та 2-4 GB RAM. Диск NVMe/SSD значно покращить продуктивність бази даних. Можна розглянути варіанти VPS з 2 vCPU та 4 GB RAM, що забезпечить хороший баланс між вартістю та продуктивністю.

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

Для більшості сценаріїв використання Shlink, VPS (віртуальний приватний сервер) є оптимальним вибором. Shlink сам по собі не є надзвичайно ресурсомістким додатком, і сучасні VPS пропонують достатньо продуктивності, гнучкості та масштабованості за доступною ціною. VPS ідеально підходить для індивідуальних розробників, невеликих команд, SaaS-стартапів на ранніх стадіях та особистих проєктів. Dedicated сервер (виділений сервер) потрібен лише в дуже специфічних випадках: якщо ви очікуєте екстремально високі навантаження (десятки мільйонів кліків на день), якщо вам потрібна максимальна продуктивність введення-виведення для бази даних, або якщо ви плануєте розміщувати на цьому ж сервері безліч інших ресурсомістких додатків, що вимагають повної ізоляції апаратних ресурсів. У більшості випадків переплачувати за dedicated сервер для Shlink не має сенсу.

Як оновити Shlink або інші компоненти?

Оновлення компонентів Docker Compose відбувається шляхом зміни тегу образу у файлі docker-compose.yml на нову версію (наприклад, shlinkio/shlink:4.0.0 на shlinkio/shlink:4.1.0) та подальшого виконання команд:


docker compose pull                 # Завантажує нові версії образів
docker compose up -d                # Перестворює контейнери з новими образами
docker image prune                  # Видаляє старі, невикористовувані образи

Перед оновленням завжди створюйте повну резервну копію бази даних та конфігураційних файлів. Оновлення ОС виконуються через sudo apt update && sudo apt upgrade -y.

Чи можу я використовувати інший веб-сервер замість Caddy (наприклад, Nginx)?

Так, ви можете використовувати Nginx або будь-який інший зворотний проксі. Для цього вам потрібно буде вручну налаштувати Nginx для проксіювання запитів до контейнера Shlink (зазвичай на внутрішній порт 8080) та окремо налаштувати отримання та оновлення TLS-сертифікатів (наприклад, за допомогою Certbot). Caddy був обраний у цьому посібнику через його простоту в налаштуванні та автоматичне керування HTTPS, що значно спрощує процес для більшості користувачів.

Як отримати GeoLite2 License Key?

Для отримання ключа GeoLite2 License Key, який Shlink використовує для геоаналітики, вам потрібно зареєструватися на сайті MaxMind. Після реєстрації ви зможете згенерувати свій ключ у розділі "My Account" -> "Manage License Keys". Вставте цей ключ у змінну GEOLITE_LICENSE_KEY у файлі .env.

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

Вітаємо! Ви успішно налаштували та розгорнули власний URL-скорочувач Shlink на вашому VPS з використанням Docker. Тепер у вас є потужний інструмент для керування посиланнями, який забезпечує повний контроль над вашими даними, брендування через власний домен та детальну аналітику переходів. Цей досвід не тільки дав вам функціональний сервіс, але й зміцнив ваші навички в роботі з Docker, Linux та адмініструванні серверів.

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

Підключення веб-клієнта Shlink: Розгорніть офіційний веб-клієнт Shlink (Shlink Web Client) в окремому Docker-контейнері або на іншому піддомені. Це надасть вам зручний графічний інтерфейс для керування посиланнями без необхідності використовувати API або командний рядок.
Інтеграція з іншими сервісами: Використовуйте потужний API Shlink для інтеграції скорочення посилань у ваші власні програми, CRM-системи або скрипти автоматизації.
Моніторинг та логування: Налаштуйте більш просунутий моніторинг вашого VPS та Docker-контейнерів за допомогою таких інструментів, як Prometheus/Grafana або ELK Stack, щоб відстежувати продуктивність та виявляти потенційні проблеми.
Масштабування: Якщо ваш Shlink стане дуже популярним, розгляньте можливість масштабування бази даних на окремий сервер або використання кластера Docker Swarm/Kubernetes для забезпечення високої доступності та обробки великих навантажень.

Налаштування власного скорочу