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

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

Після встановлення всіх компонентів необхідно налаштувати BookStack та веб-сервер Caddy для їхньої спільної роботи.

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

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

cd /var/www/bookstack
cp .env.example .env

Тепер відкрийте файл .env для редагування:

sudo nano .env

Знайдіть та відредагуйте наступні рядки, замінивши значення на свої:

• APP_URL: Вкажіть повний URL вашого BookStack (наприклад, https://your-bookstack-domain.com).
• DB_DATABASE: Ім'я вашої бази даних MySQL (наприклад, bookstack_db).
• DB_USERNAME: Ім'я користувача MySQL для BookStack (наприклад, bookstack_user).
• DB_PASSWORD: Пароль користувача MySQL для BookStack.

Приклад відредагованих рядків:

APP_URL=https://your-bookstack-domain.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=bookstack_db
DB_USERNAME=bookstack_user
DB_PASSWORD=ВАШ_НАДІЙНИЙ_ПАРОЛЬ_ДЛЯ_БД

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

2. Генерація ключа програми

BookStack вимагає унікального ключа програми для шифрування та безпеки. Виконайте наступну команду в директорії BookStack:

php artisan key:generate

Ця команда автоматично згенерує ключ та додасть його до вашого файлу .env.

3. Виконання міграцій бази даних

Тепер необхідно створити таблиці в базі даних BookStack.

php artisan migrate --force # Виконання міграцій бази даних

При запиті підтвердження введіть yes.

4. Налаштування Caddyfile

Caddy автоматично керує HTTPS, що робить його ідеальним для BookStack. Відредагуйте файл конфігурації Caddy за замовчуванням:

sudo nano /etc/caddy/Caddyfile

Видаліть весь вміст файлу та вставте наступну конфігурацію. Замініть your-bookstack-domain.com на ваш фактичний домен:

your-bookstack-domain.com {
    # Вказуємо кореневу директорію BookStack
    root  /var/www/bookstack/public

    # Вмикаємо сервер статичних файлів
    file_server

    # Проксіюємо PHP запити до PHP-FPM
    php_fastcgi unix//run/php/php8.3-fpm.sock

    # Налаштовуємо логування доступу
    log {
        output file /var/log/caddy/access.log
        format json
    }

    # Обробка помилок
    handle_errors {
        rewrite  /index.php
    }

    # Швидке перенаправлення HTTP на HTTPS
    # Caddy робить це автоматично, але цей рядок може допомогти в деяких випадках
    # Або можна використовувати {
    #   redir https://{host}{uri}
    # }
}

sudo mkdir -p /var/log/caddy
sudo chown caddy:caddy /var/log/caddy # Встановлення власника для директорії логів

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

sudo systemctl reload caddy

sudo systemctl status caddy

curl -I https://your-bookstack-domain.com

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

Регулярне резервне копіювання — це наріжний камінь будь-якої production-системи. BookStack зберігає дані в базі даних та файли (зображення, вкладення) на диску. Обслуговування включає оновлення ПЗ та моніторинг.

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

• База даних BookStack: Містить усі сторінки, книги, розділи, користувачів, налаштування. Це найважливіше.
• Файли BookStack: Включають завантажені зображення, вкладення, а також файл .env (з конфіденційними даними, такими як ключ програми та облікові дані БД).

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

Створимо простий скрипт для резервного копіювання. Рекомендується зберігати резервні копії не на тому ж сервері.

sudo nano /usr/local/bin/bookstack_backup.sh

Вставте наступний вміст, замінивши ВАШ_НАДЕЖНЫЙ_ПАРОЛЬ_ДЛЯ_БД та bookstack_db на свої значення:

#!/bin/bash

# Конфігурація
DB_NAME="bookstack_db"
DB_USER="bookstack_user" # Краще створити окремого користувача MySQL лише для резервного копіювання з правами SELECT, LOCK TABLES
DB_PASS="ВАШ_НАДЕЖНЫЙ_ПАРОЛЬ_ДЛЯ_БД"
BOOKSTACK_PATH="/var/www/bookstack"
BACKUP_DIR="/var/backups/bookstack"
DATE=$(date +%Y%m%d%H%M%S)
FILENAME_DB="${DB_NAME}_${DATE}.sql"
FILENAME_FILES="bookstack_files_${DATE}.tar.gz"

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

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

# 1. Резервне копіювання бази даних
echo "Резервне копіювання бази даних..."
mysqldump --user="${DB_USER}" --password="${DB_PASS}" "${DB_NAME}" > "${BACKUP_DIR}/${FILENAME_DB}"
if [ $? -eq 0 ]; then
    echo "Резервне копіювання бази даних успішно створено: ${FILENAME_DB}"
else
    echo "Помилка при створенні резервної копії бази даних."
    exit 1
fi

# 2. Резервне копіювання файлів BookStack (за винятком кешу та логів)
echo "Резервне копіювання файлів BookStack..."
tar -czf "${BACKUP_DIR}/${FILENAME_FILES}" -C "${BOOKSTACK_PATH}" \
    --exclude='storage/uploads/images/' \
    --exclude='storage/uploads/files/' \
    --exclude='storage/logs/' \
    --exclude='bootstrap/cache/' \
    --exclude='vendor/' \
    .
# Додатково зберігаємо лише .env та uploads окремо, щоб їх легко було відновити
cp "${BOOKSTACK_PATH}/.env" "${BACKUP_DIR}/bookstack_env_${DATE}.env"
tar -czf "${BACKUP_DIR}/bookstack_uploads_images_${DATE}.tar.gz" -C "${BOOKSTACK_PATH}/storage/uploads" images
tar -czf "${BACKUP_DIR}/bookstack_uploads_files_${DATE}.tar.gz" -C "${BOOKSTACK_PATH}/storage/uploads" files

if [ $? -eq 0 ]; then
    echo "Резервне копіювання файлів BookStack успішно створено: ${FILENAME_FILES}"
else
    echo "Помилка при створенні резервної копії файлів BookStack."
    exit 1
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
find "${BACKUP_DIR}" -type f -name ".env" -mtime +7 -delete

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

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

sudo crontab -e

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

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

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

Ніколи не зберігайте всі резервні копії лише на тому ж сервері, що й основний сервіс! Якщо сервер вийде з ладу, ви втратите все.

• Зовнішнє S3-сумісне сховище: Amazon S3, DigitalOcean Spaces, Backblaze B2. Це надійний і відносно недорогий варіант. Можна використовувати утиліти на кшталт s3cmd або rclone для автоматичної синхронізації.
• Окремий VPS: Орендуйте невеликий, дешевий VPS виключно для зберігання резервних копій та синхронізуйте їх туди по SFTP/RSYNC.
• Локальний мережевий диск (NAS): Якщо у вас є власна інфраструктура.

Наприклад, для відправки резервних копій на S3, ви можете додати до скрипта bookstack_backup.sh після створення архівів команду s3cmd put "${BACKUP_DIR}/${FILENAME_DB}" s3://your-s3-bucket/bookstack/ (потрібна установка та налаштування s3cmd).

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

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

• Системні оновлення (ОС, PHP, MySQL):
  • Rolling (постійні): Для некритичних патчів безпеки можна налаштувати автоматичне оновлення (наприклад, за допомогою unattended-upgrades).
  • Maintenance Window (вікно обслуговування): Для мажорних оновлень PHP, MySQL або ядра Linux рекомендується планувати вікно обслуговування, оскільки вони можуть вимагати перезавантаження сервера або призвести до тимчасової непрацездатності сервісу. Тестуйте оновлення на стейджинг-сервері, якщо це можливо.

  
  sudo apt update && sudo apt upgrade -y # Оновлення системи
  

• Оновлення BookStack:

  BookStack оновлюється через Git та Composer. Рекомендується виконувати їх у вікно обслуговування.

  
  cd /var/www/bookstack
  git pull # Завантаження останніх змін з репозиторію
  composer install --no-dev # Оновлення залежностей
  php artisan migrate --force # Виконання міграцій бази даних (якщо є)
  php artisan cache:clear # Очищення кешу BookStack
  php artisan view:clear # Очищення кешу представлень
  sudo chown -R www-data:www-data /var/www/bookstack # Переконайтеся, що права вірні після pull
  sudo chmod -R 775 /var/www/bookstack/storage /var/www/bookstack/bootstrap/cache
  sudo systemctl reload php8.3-fpm # Перезапуск PHP-FPM
  sudo systemctl reload caddy # Перезапуск Caddy
  

  Завжди перевіряйте офіційну документацію BookStack перед оновленням, оскільки процес може змінюватися.

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

Мій BookStack не працює, я бачу помилку 500 або порожню сторінку. Що робити?

Помилка 500 (Internal Server Error) зазвичай вказує на проблему в роботі PHP або програми. В першу чергу перевірте логи:

• Логи Caddy: sudo tail -f /var/log/caddy/access.log та sudo journalctl -u caddy -f. Шукайте помилки, пов'язані з проксіюванням PHP.
• Логи PHP-FPM: sudo tail -f /var/log/php8.3-fpm.log (або відповідна версія PHP).
• Логи BookStack: sudo tail -f /var/www/bookstack/storage/logs/laravel.log. Це найважливіший лог для налагодження проблем самого BookStack.

Часті причини: неправильні права доступу до файлів/директорій (особливо storage та bootstrap/cache), помилки у файлі .env (невірні облікові дані БД, неправильний APP_URL), відсутні PHP-розширення, проблеми з підключенням до бази даних.

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

Для невеликого особистого використання або команди з 2-3 осіб з не дуже великим обсягом даних, мінімально підійде VPS з 1-2 vCPU, 2 ГБ оперативної пам'яті та 40 ГБ SSD-диска. Цього достатньо для стабільної роботи Ubuntu 24.04 LTS, PHP 8.3/8.4, MySQL 8.0 та Caddy з BookStack. Важливо, щоб диск був SSD для хорошої продуктивності бази даних.

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

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

Я змінив доменне ім'я. Що потрібно оновити?

Якщо ви змінили доменне ім'я, необхідно оновити як мінімум два місця:

1. Файл .env BookStack: Змініть значення APP_URL на нове доменне ім'я (наприклад, APP_URL=https://new-domain.com).
2. Caddyfile: Відредагуйте /etc/caddy/Caddyfile і замініть старе доменне ім'я на нове в першому рядку (наприклад, new-domain.com { ... }).

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

Процес оновлення BookStack зазвичай включає: перехід до директорії BookStack (cd /var/www/bookstack), отримання останніх змін з Git (git pull), оновлення PHP-залежностей через Composer (composer install --no-dev), виконання міграцій бази даних (php artisan migrate --force) та очищення кешу BookStack (php artisan cache:clear && php artisan view:clear). Завжди рекомендується прочитати офіційні інструкції з оновлення для конкретної версії BookStack, оскільки можуть бути специфічні кроки.

BookStack видає помилку "Access Denied" при спробі підключення до MySQL.

Ця помилка означає, що BookStack не може підключитися до бази даних MySQL з наданими обліковими даними. Перевірте наступне:

• Файл .env: Переконайтеся, що DB_USERNAME, DB_PASSWORD та DB_DATABASE у файлі /var/www/bookstack/.env точно відповідають тим, що ви створили в MySQL.
• Користувач MySQL: Переконайтеся, що користувач bookstack_user існує в MySQL і має правильні привілеї на базу даних bookstack_db. Ви можете перевірити це, увійшовши в MySQL від імені root і виконавши SELECT user, host FROM mysql.user; та SHOW GRANTS FOR 'bookstack_user'@'localhost';.
• Служба MySQL: Перевірте, що служба MySQL запущена: sudo systemctl status mysql.

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

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

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

• Налаштування користувачів та ролей: У BookStack ви можете створювати користувачів, групи та призначати їм різні права доступу до книг, розділів та сторінок. Почніть зі створення облікових записів для вашої команди та налаштування відповідних дозволів.
• Кастомізація зовнішнього вигляду: BookStack дозволяє змінювати логотип, колірну схему та додавати користувацький CSS, щоб брендувати вашу вікі відповідно до вашого стилю.
• Інтеграція із зовнішніми сервісами: Розгляньте можливість налаштування єдиного входу (SSO) через LDAP, SAML2 або соціальні провайдери, якщо це актуально для вашої команди.
• Моніторинг сервера: Встановіть системи моніторингу (наприклад, Prometheus + Grafana або Zabbix) для відстеження завантаження CPU, RAM, диска та стану сервісів, щоб оперативно реагувати на потенційні проблеми.