Як самостійно розгорнути HedgeDoc у 2026 році: WebSockets, OAuth і завантажені файли

Є дві версії «запустити HedgeDoc»: контейнер існує або сервіс виконує свою справжню роботу. Важлива лише друга. Тут перевіркою є створення нотатки, її одночасне редагування у двох браузерах, завантаження зображення та автентифікація через вибраного провайдера.

HedgeDoc призначений саме для цього: спільних Markdown-нотаток у реальному часі. Розгортання має зберегти компоненти, що забезпечують таку поведінку; порт, volume і сертифікат — це вхідні дані, а не результат.

Створіть резервну копію стану, який HedgeDoc не може відтворити

Визначте цільову точку та час відновлення HedgeDoc з урахуванням бази даних, завантажених файлів і конфігурації автентифікації. Підключіть /hedgedoc/public/uploads до bootstrap, запишіть нешкідливі тестові дані та замініть контейнер, щоб довести фактичну постійність цього шляху. Іменований volume забезпечує збереження даних під час повторного розгортання, але не захищає від компрометації чи втрати сервера.

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

Відокремте HedgeDoc від його залежностей

Стан процесу та стан продукту — це різні речі для HedgeDoc. Порт 3000 може відповідати, навіть якщо користувацька транзакція все ще не працює. Мережевий контракт HedgeDoc включає Postgres, а також опційні OAuth- і SMTP-провайдери. Залишайте приватні endpoints у внутрішньому DNS, дозволяйте лише необхідні вихідні з’єднання та надайте HedgeDoc service credential з обмеженими правами.

Використовуйте цю перевірку готовності після суттєвих змін конфігурації: створіть нотатку, одночасно відредагуйте її у двох браузерах, завантажте зображення та пройдіть автентифікацію через вибраного провайдера. Не додавайте дорогі зовнішні перевірки до liveness probes, щоб збій провайдера не спричинив цикл перезапусків. Під час роботи з capacity відстежуйте WebSocket connections, database writes, uploaded media та document history — це точніше відображає реальне навантаження HedgeDoc, ніж запити сторінок.

П’ять перевірок, надійніших за health контейнера

Перетворіть smoke test HedgeDoc на повторювану release-команду або короткий runbook. Її результат має демонструвати такий сценарій: створення нотатки, одночасне редагування у двох браузерах, завантаження зображення та автентифікація через вибраного провайдера. Разом із результатом збережіть версію застосунку, digest контейнера, hostname маршруту та ідентифікатор тестових даних.

Запускайте ту саму перевірку після планової заміни контейнера та після відновлення бази даних, завантажених файлів і конфігурації автентифікації в іншому середовищі. Відновлення вважається успішним, коли нотатки, ревізії, користувачі й завантажені файли повернулися, а два браузери можуть спільно працювати з відновленою нотаткою. Порівнюйте час і споживання ресурсів, пов’язані з WebSocket connections, database writes, uploaded media та document history; суттєва зміна заслуговує на перевірку, навіть якщо фінальна дія все ще завершується успішно.

Потім виконайте безпечну перевірку відмови: тимчасово забороніть тестовій identity доступ до Postgres, а також опційних OAuth- і SMTP-провайдерів. Переконайтеся, що HedgeDoc повідомляє про проблему та повертається до нормальної роботи без руйнівних ручних змін. Збережіть лише необхідний, редагований фрагмент логу. Цей чотирикомпонентний gate охоплює запуск, постійність даних, відновлення та обробку відмов.

Запускайте HedgeDoc, не приховуючи важливих компонентів

Мінімальна команда корисна, коли вона показує, чим платформа керуватиме надалі.

docker run -d \
  --name hedgedoc \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -v hedgedoc-data:/hedgedoc/public/uploads \
  -e CMD_SESSION_SECRET=replace-with-a-long-random-value \
  -e CMD_DOMAIN=app.example.com \
  -e CMD_PROTOCOL_USESSL=true \
  -e CMD_DB_URL=postgres://hedgedoc:replace-password@postgres.internal:5432/hedgedoc \
  quay.io/hedgedoc/hedgedoc:latest

Тут порт 3000 залишається приватним для host, а кожен необхідний шлях явно вказано. Додайте перевірені connection settings для Postgres, а також опційних OAuth- і SMTP-провайдерів; для приватних сервісів використовуйте приватні імена. Перевірте запуск за логами та за допомогою специфічної для застосунку перевірки: створіть нотатку, одночасно відредагуйте її у двох браузерах, завантажте зображення та пройдіть автентифікацію через вибраного провайдера. Після перевірки зафіксуйте версію image, щоб планова заміна непомітно не змінила поведінку.

Не надавайте HedgeDoc доступ до всього host

Для HedgeDoc цінна attack surface не обов’язково пов’язана з landing page. Основна помилка — використати приклад session secret або ненавмисно дозволити анонімне створення нотаток. Протидійте цьому свідомо: використовуйте стабільний session secret, визначте, чи прийнятне анонімне створення нотаток, і обмежте доступ до приватних нотаток.

Згенеруйте CMD_SESSION_SECRET як довге випадкове значення; його ротація зазвичай анулює сесії або токени, тому сплануйте вплив на користувачів, а не називайте це міграцією шифрування. Використовуйте непривілейованого користувача контейнера, якщо image це підтримує, і не підключайте сторонні credentials. Застосуйте обмеження швидкості або розміру на ingress, де ненадійні операції можуть споживати WebSocket connections, database writes, uploaded media та document history.

Тестуйте HedgeDoc із зовнішньої мережі

Виберіть фінальний hostname HedgeDoc до того, як користувачі збережуть callbacks або client settings, а потім задайте CMD_DOMAIN і CMD_PROTOCOL_USESSL для публічного URL. Platform route має завершувати TLS один раз і спрямовувати трафік на приватний порт 3000.

Запустіть acceptance transaction ззовні. Якщо клієнт взагалі не досягає HedgeDoc, скористайтеся чеклістом перевірки SSL для перевірки DNS і сертифіката. Якщо запит доходить до HedgeDoc, але редагування в реальному часі не працює через неправильні WebSockets або domain settings, припиніть змінювати proxy redirects і перевірте специфічну для застосунку boundary.

Експлуатуйте HedgeDoc з урахуванням його реального bottleneck

Використовуйте сценарій створення нотатки, її одночасного редагування у двох браузерах, завантаження зображення та автентифікації через вибраного провайдера як smoke test HedgeDoc після кожного deployment. Супровідні метрики — WebSocket connections, database writes, uploaded media та document history; налаштовуйте alert там, де ці ресурси наближаються до рівня, що погіршує користувацьку дію.

Основний ризик змін полягає в тому, що database migrations HedgeDoc, OAuth settings і зміни plugin або renderer потребують staged release. Безпечний release починається з snapshot, який можна відновити, і перевіряє будь-яку односторонню зміну стану до перемикання трафіку. Коли редагування в реальному часі не працює через неправильні WebSockets або domain settings, не видаляйте несправний контейнер, доки не прочитаєте його конфігурацію та першу помилку.

Як Dockup спрощує роботу з HedgeDoc

Dockup може взяти на себе змінні компоненти платформи: спрямувати трафік на порт 3000, видати domain і certificate, передати secrets, підключити persistent storage та з’єднати HedgeDoc із керованими або приватно підключеними сервісами. Це можна зробити на інфраструктурі Dockup або на підключеному вами сервері.

Acceptance work для HedgeDoc залишається явною частиною процесу. Після one-click deployment задайте CMD_DOMAIN і CMD_PROTOCOL_USESSL для публічного URL, підключіть і протестуйте Postgres, а також опційних OAuth- і SMTP-провайдерів, і запустіть цей сценарій: створіть нотатку, одночасно відредагуйте її у двох браузерах, завантажте зображення та пройдіть автентифікацію через вибраного провайдера. Такий розподіл навмисний: Dockup усуває повторюване налаштування інфраструктури, не вдаючи, що ролі застосунку, credentials провайдерів або політика відновлення визначаються самі.

Поширені запитання

Що потрібно HedgeDoc для production deployment?

Спрямуйте контейнер HedgeDoc на порту 3000 через один HTTPS origin. Мережева вимога для залежностей — Postgres, а також опційні OAuth- і SMTP-провайдери. Не вважайте HedgeDoc готовим, доки не зможете створити нотатку, одночасно відредагувати її у двох браузерах, завантажити зображення та пройти автентифікацію через вибраного провайдера.

Які дані HedgeDoc потрібно включити до резервної копії?

Збережіть /hedgedoc/public/uploads і включіть базу даних, завантажені файли та конфігурацію автентифікації до одного recovery manifest. Чисте відновлення HedgeDoc вважається успішним лише тоді, коли нотатки, ревізії, користувачі й завантажені файли повернулися, а два браузери можуть спільно працювати з відновленою нотаткою.

Чи потрібен HedgeDoc HTTPS за reverse proxy?

Використовуйте HTTPS для публічного origin HedgeDoc, а порт 3000 залиште у внутрішньому route. Правильно застосуйте налаштування HedgeDoc: задайте CMD_DOMAIN і CMD_PROTOCOL_USESSL для публічного URL. Для HedgeDoc HTTPS захищає credentials або вміст користувачів під час передавання та забезпечує узгоджену поведінку клієнта, залежну від origin.

Як тестувати upgrade HedgeDoc?

Відновіть поточний стан HedgeDoc в ізольованому deployment, застосуйте candidate version і повторіть acceptance transaction. Приділіть особливу увагу цьому процесу, оскільки database migrations HedgeDoc, OAuth settings і зміни plugin або renderer потребують staged release. Зберігайте попередній image HedgeDoc, доки не буде зрозумілою межа міграції даних і rollback.