Встановлення Keycloak на VPS

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

Після запуску контейнерів Keycloak та PostgreSQL, необхідно налаштувати зворотний проксі Caddy для забезпечення HTTPS та коректної роботи Keycloak із зовнішнім доступом.

1. Налаштування Caddy для Keycloak

Відредагуйте конфігураційний файл Caddy. За замовчуванням він знаходиться в /etc/caddy/Caddyfile.

sudo nano /etc/caddy/Caddyfile

Видаліть весь вміст за замовчуванням і вставте наступне. Замініть auth.yourdomain.com на ваш домен Keycloak.

auth.yourdomain.com {
    # Увімкнути автоматичний HTTPS з Let's Encrypt
    tls {
        dns cloudflare {env.CLOUDFLARE_API_TOKEN} # Якщо ви використовуєте Cloudflare для DNS, вкажіть токен API
        # Якщо не використовуєте Cloudflare DNS, просто залиште tls
    }

    # Налаштування для проксування запитів до Keycloak
    reverse_proxy keycloak:8080 {
        # Передаємо важливі заголовки для коректної роботи Keycloak за проксі
        header_up Host {host}
        header_up X-Real-IP {remote_ip}
        header_up X-Forwarded-For {remote_ip}
        header_up X-Forwarded-Proto {scheme}
        header_up X-Forwarded-Host {host}
    }

    # Налаштування для безпеки
    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"
        # Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';" # Налаштуйте за необхідності
    }

    # Логування
    log {
        output file /var/log/caddy/keycloak_access.log
        format json
    }
}

Примітка щодо tls: Якщо ви використовуєте DNS-провайдера, відмінного від Cloudflare, або не хочете використовувати DNS-челендж, ви можете просто залишити рядок tls. Caddy спробує використовувати HTTP-01 челендж, який вимагає, щоб порт 80 був доступний ззовні. Якщо ви використовуєте Cloudflare, як у прикладі, то вам потрібно буде створити файл /etc/caddy/Caddyfile.env:

sudo nano /etc/caddy/Caddyfile.env

І додайте туди ваш Cloudflare API Token:

CLOUDFLARE_API_TOKEN=YOUR_CLOUDFLARE_API_TOKEN

Переконайтеся, що цей токен має права на керування DNS-записами для вашого домену.

Збережіть файл(и). Перевірте конфігурацію Caddy та перезапустіть його:

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

Якщо валідація пройшла успішно, Caddy перезапуститься і спробує отримати TLS-сертифікат.

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

Після всіх налаштувань, необхідно переконатися, що Keycloak запущено та він доступний.

Перевірка контейнерів

Переконайтеся, що обидва контейнери працюють:

docker compose ps

Вивід повинен показати State: Up для обох сервісів.

Перевірка доступності Keycloak через домен

Відкрийте в браузері адресу https://auth.yourdomain.com/admin (замініть на ваш домен). Ви повинні побачити сторінку входу в адміністративну консоль Keycloak.

Введіть логін admin та пароль, який ви вказали у файлі .env (KEYCLOAK_ADMIN_PASSWORD).

Перевірка конфігурації OpenID Connect

Ви можете перевірити, що Keycloak коректно віддає свою конфігурацію OpenID Connect:

curl -k https://auth.yourdomain.com/realms/master/.well-known/openid-configuration

Ви повинні отримати JSON-відповідь з метаданими OpenID Connect для стандартного realm master.

Якщо всі кроки виконано правильно, Keycloak повністю встановлено та сконфігуровано для роботи з HTTPS та базою даних PostgreSQL.

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

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

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

• База даних PostgreSQL: Це найважливіший компонент, оскільки він містить всю інформацію про користувачів, realm'и, клієнтів, ролі та сесії Keycloak.
• Конфігурація Keycloak: У нашому випадку з Docker Compose, основні налаштування Keycloak задані у файлах docker-compose.yml та .env. Однак, якщо ви робили будь-які специфічні зміни всередині контейнера (що не рекомендується для Dockerized застосунків), їх також потрібно резервувати. Також корисно зберігати томи keycloak-data та postgres-data.
• Конфігурація Caddy: Файл /etc/caddy/Caddyfile і, можливо, /etc/caddy/Caddyfile.env.
• Логи: Для налагодження та аудиту. Хоча вони не критичні для відновлення, вони корисні.

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

Створимо простий bash-скрипт, який виконуватиме дамп бази даних та архівуватиме важливі файли.

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

sudo mkdir -p /var/backups/keycloak
sudo nano /usr/local/bin/keycloak_backup.sh

Вставте наступний вміст. Замініть keycloak-sso на ім'я вашої директорії з файлами Docker Compose, якщо воно відрізняється.

#!/bin/bash

# Шлях до директорії з файлами Docker Compose
DOCKER_COMPOSE_DIR="/home/youruser/keycloak-sso" # Вкажіть повний шлях до вашої директорії keycloak-sso
# Директорія для зберігання резервних копій
BACKUP_DIR="/var/backups/keycloak"
# Ім'я файлу .env
ENV_FILE="${DOCKER_COMPOSE_DIR}/.env"

# Завантажуємо змінні оточення з .env
if [ -f "$ENV_FILE" ]; then
    export $(grep -v '^#' "$ENV_FILE" | xargs)
else
    echo "Помилка: Файл .env не знайдено за шляхом $ENV_FILE"
    exit 1
fi

DATE=$(date +%Y%m%d%H%M%S)
BACKUP_FILENAME="${BACKUP_DIR}/keycloak_backup_${DATE}.tar.gz"
DB_DUMP_FILE="${BACKUP_DIR}/keycloak_db_dump_${DATE}.sql"

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

# 1. Резервне копіювання бази даних PostgreSQL
echo "Створення дампу бази даних PostgreSQL..."
docker compose -f "${DOCKER_COMPOSE_DIR}/docker-compose.yml" exec -T db pg_dump -U keycloak -d keycloak > "$DB_DUMP_FILE"
if [ $? -eq 0 ]; then
    echo "Дамп БД успішно створено: $DB_DUMP_FILE"
else
    echo "Помилка при створенні дампу БД."
    exit 1
fi

# 2. Архівування важливих файлів та даних
echo "Архівування конфігураційних файлів та даних..."
tar -czf "$BACKUP_FILENAME" \
    --absolute-names \
    "${DOCKER_COMPOSE_DIR}/docker-compose.yml" \
    "${DOCKER_COMPOSE_DIR}/.env" \
    "$DB_DUMP_FILE" \
    "/etc/caddy/Caddyfile" \
    "/etc/caddy/Caddyfile.env" \
    "${DOCKER_COMPOSE_DIR}/keycloak-data" \
    "${DOCKER_COMPOSE_DIR}/postgres-data" # Додаємо персистентні томи

if [ $? -eq 0 ]; then
    echo "Архів резервної копії успішно створено: $BACKUP_FILENAME"
else
    echo "Помилка при створенні архіву резервної копії."
    exit 1
fi

# 3. Видалення тимчасового дампу БД
rm "$DB_DUMP_FILE"

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

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

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

sudo chmod +x /usr/local/bin/keycloak_backup.sh

3. Планування резервного копіювання за допомогою Cron

Додамо скрипт до розкладу Cron для щоденного виконання (наприклад, о 3:00 ранку).

sudo crontab -e

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

0 3 * * * /usr/local/bin/keycloak_backup.sh >> /var/log/keycloak_backup.log 2>&1

Цей рядок запускатиме скрипт щодня о 3:00 ночі, а вивід перенаправлятиметься у файл логів /var/log/keycloak_backup.log.

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

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

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

Наприклад, для завантаження в S3 за допомогою rclone, ви б додали до скрипта рядок після створення архіву:

# rclone copy "$BACKUP_FILENAME" "remote_s3_storage:keycloak-backups/"

Попередньо налаштувавши rclone з вашими S3-обліковими даними.

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

• Оновлення ОС та Docker: Регулярно оновлюйте операційну систему та Docker. Для Ubuntu це sudo apt update && sudo apt upgrade -y. Робіть це у плановий час, оскільки іноді потрібне перезавантаження сервера.
• Оновлення Keycloak: Для Keycloak у Docker Compose, це зводиться до зміни версії образу в docker-compose.yml (наприклад, з 25.0.0 на 25.0.1) та подальшого виконання docker compose pull keycloak && docker compose up -d. Перед оновленням завжди читайте примітки до релізу, оскільки можуть бути зміни у конфігурації або міграції БД.
• Оновлення PostgreSQL: Оновлення мажорних версій PostgreSQL (наприклад, з 16 на 17) вимагає складнішої процедури міграції даних. Це завжди має виконуватися в рамках запланованого "вікна обслуговування" (maintenance window) з попереднім резервним копіюванням. Мінорні оновлення (наприклад, 17.0 на 17.1) зазвичай безпечні та не вимагають міграції.

Для production-систем завжди рекомендується мати тестове середовище, де ви можете спочатку перевірити оновлення, перш ніж застосовувати їх на основному сервері.

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

У цьому розділі ми розглянемо типові проблеми, які можуть виникнути під час встановлення та налаштування Keycloak, а також відповімо на поширені запитання.

Keycloak не запускається / Помилка підключення до БД

Проблема: Контейнер Keycloak постійно перезапускається або видає помилки підключення до бази даних у логах. Що перевірити:

1. Логи Keycloak: docker compose logs keycloak. Шукайте повідомлення про помилки підключення до PostgreSQL.
2. Логи PostgreSQL: docker compose logs db. Переконайтеся, що PostgreSQL успішно запущено та він слухає з'єднання.
3. Змінні оточення: Перевірте правильність KC_DB_URL, KC_DB_USERNAME, KC_DB_PASSWORD у docker-compose.yml та .env. Переконайтеся, що паролі збігаються.
4. Healthcheck PostgreSQL: Переконайтеся, що healthcheck для контейнера db проходить успішно (docker compose ps). Keycloak не запуститься, доки БД не буде готова.

Не можу отримати доступ до адмінки Keycloak через домен

Проблема: При спробі відкрити https://auth.yourdomain.com/admin браузер показує помилку "Connection refused" або "ERR_CONNECTION_CLOSED". Що перевірити:

1. DNS-запис: Переконайтеся, що ваш домен (наприклад, auth.yourdomain.com) коректно вказує на IP-адресу вашого VPS. Використовуйте dig auth.yourdomain.com.
2. Файрвол (UFW): Перевірте, що порти 80 і 443 відкриті: sudo ufw status.
3. Caddy: Перевірте статус Caddy: sudo systemctl status caddy. Переконайтеся, що його запущено і немає помилок у його логах: sudo journalctl -u caddy.
4. Конфігурація Caddyfile: Перевірте, що домен у Caddyfile збігається з вашим, і що reverse_proxy правильно вказує на контейнер Keycloak (keycloak:8080).
5. Змінна KC_PROXY: Переконайтеся, що в docker-compose.yml для Keycloak встановлена змінна KC_PROXY: edge.

Проблеми з HTTPS / Caddy не отримує сертифікат

Проблема: Caddy не може отримати TLS-сертифікат від Let's Encrypt, і сайт доступний лише за HTTP (або взагалі недоступний). Що перевірити:

1. Логи Caddy: sudo journalctl -u caddy --no-pager. Шукайте помилки, пов'язані з tls або Let's Encrypt.
2. Доступність порту 80/443: Переконайтеся, що жодні інші сервіси не займають порти 80 або 443. (sudo lsof -i :80, sudo lsof -i :443).
3. DNS-запис: Переконайтеся, що ваш домен правильно вказує на ваш VPS. Let's Encrypt перевіряє володіння доменом.
4. Конфігурація DNS-челенджу (якщо використовується): Якщо ви використовуєте tls { dns ... }, перевірте, що змінна оточення з API-токеном коректно встановлена і сам токен має потрібні права.

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

Проблема: Ви забули пароль адміністратора Keycloak. Що перевірити: Пароль адміністратора встановлюється змінною KEYCLOAK_ADMIN_PASSWORD у файлі .env. Як виправити:

1. Відредагуйте файл .env та змініть значення KEYCLOAK_ADMIN_PASSWORD на новий, надійний пароль.
2. Перезапустіть контейнер Keycloak, щоб зміни набули чинності: docker compose restart keycloak.
3. Тепер ви зможете увійти до адмін-консолі з новим паролем.

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

Мінімально відповідний VPS-конфіг для встановлення Keycloak для невеликого проєкту (до 500 активних користувачів) включає 2 vCPU, 4 GB оперативної пам'яті та 50 GB SSD-диска. Цього має бути достатньо для запуску операційної системи, Keycloak та його бази даних PostgreSQL. Важливо, щоб диск був SSD для забезпечення достатньої продуктивності бази даних. При збільшенні навантаження або кількості користувачів знадобиться масштабування ресурсів.

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

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

Як масштабувати Keycloak?

Проблема: Ваша інсталяція Keycloak відчуває високе навантаження, і продуктивності поточного VPS недостатньо. Що перевірити: Моніторинг CPU, RAM, I/O диска на вашому VPS. Логи Keycloak на предмет затримок або помилок. Як виправити:

1. Вертикальне масштабування (Scale Up): Збільште ресурси вашого поточного VPS (CPU, RAM, Disk). Це найпростіший перший крок.
2. Горизонтальне масштабування (Scale Out): Розгорніть кілька екземплярів Keycloak за балансувальником навантаження. Це вимагає налаштування Keycloak у кластерному режимі (із загальною базою даних та кешем).
3. Оптимізація бази даних: Переконайтеся, що PostgreSQL має достатньо ресурсів та налаштований для оптимальної продуктивності.
4. Оптимізація Keycloak: Налаштуйте параметри JVM, кешування та логування для кращої продуктивності.