Як розгорнути Vikunja на власному сервері у 2026 році: публічний URL, база даних і файлове сховище

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

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

Від чого залежить Vikunja

Окресліть навколо Vikunja три межі: вхідний трафік до порту 3456, постійний стан і допоміжні вимоги. Контейнер можна замінити, але для двох інших складових потрібно явно визначити відповідальних. Мережева угода для Vikunja у production-командах передбачає Postgres або MySQL і SMTP. Приватні endpoints залишайте у внутрішньому DNS, дозволяйте лише необхідні вихідні з’єднання та надайте Vikunja облікові дані service account з обмеженими правами.

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

Volumes — лише перший рівень відновлення

Зафіксуйте стан до створення першого реального запису: базу даних, завантажені файли та конфігурацію. Підключіть /app/vikunja/files до bootstrap, запишіть нешкідливі тестові дані та замініть контейнер, щоб довести, що цей шлях справді постійний. Перевірте mount, записавши нешкідливі дані, замінивши Vikunja та прочитавши їх знову.

Snapshots цінні для швидкого відкату, але коли хост або volume зникає, потрібна незалежна резервна копія. Відновіть дані у порожньому середовищі із зафіксованим образом і перевірте, що проєкти, історія завдань, вкладення, нагадування та користувачі повернулися, а заплановане сповіщення все ще надходить. Використовуйте persistent volumes і snapshots, щоб розділяти ці два механізми відновлення.

Захистіть найціннішу частину Vikunja

Після першого входу перевірте, що може робити анонімний відвідувач, звичайний користувач і адміністратор. Помилка у Vikunja, якої слід уникати, — використання незміненого JWT secret або випадково відкритої реєстрації. Передбачена політика полягає у використанні стабільного JWT secret, вимкненні реєстрації після завершення набору користувачів і розмежуванні звичайних учасників та адміністраторів проєктів.

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

Перетворіть smoke test Vikunja на перевірку релізу

Release candidate для Vikunja отримує право обслуговувати трафік після проходження фіксованого сценарію: створити проєкт, завдання, вкладення й нагадування, перемістити завдання на дошці та перевірити подію в календарі й сповіщення. Зафіксуйте digest образу, ефективну конфігурацію без секретів, публічний origin і часові мітки цього сценарію. Тестові дані мають бути одноразовими, але достатньо реалістичними, щоб пройти той самий шлях, що й користувачі.

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

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

Створіть замінний контейнер Vikunja

Наступна команда робить межу контейнера видимою, не створюючи ілюзії, що вона налаштовує всі зовнішні сервіси.

docker run -d \
  --name vikunja \
  --restart unless-stopped \
  -p 127.0.0.1:3456:3456 \
  -v vikunja-data:/app/vikunja/files \
  -e VIKUNJA_SERVICE_JWTSECRET=replace-with-a-long-random-value \
  vikunja/vikunja:latest

Перш ніж відкривати ingress, перевірте розгорнуте середовище, mounts і listener. Додайте перевірені параметри підключення до Postgres або MySQL і SMTP для production-команд; для приватних сервісів використовуйте приватні імена. Успішний запуск завершується тоді, коли ви можете створити проєкт, завдання, вкладення й нагадування, перемістити завдання на дошці та перевірити подію в календарі й сповіщення, а не тоді, коли docker ps виводить Up.

Маршрутизуйте Vikunja без неправдивого HTTPS

Уникайте тимчасових і постійних public origins для Vikunja. Натомість задайте VIKUNJA_SERVICE_PUBLICURL точному HTTPS origin, спрямуйте вибране DNS-ім’я на маршрут платформи та проксуйте трафік лише до порту 3456.

Виконайте цю дію ззовні хоста: створіть проєкт, завдання, вкладення й нагадування, перемістіть завдання на дошці та перевірте подію в календарі й сповіщення. Якщо ingress не працює, посібник з усунення помилки 502 охоплює помилки портів і listener. Якщо Vikunja отримує запит, але публічний URL API неправильний або завантажені файли не зберігаються у volume, тепер докази вказують за межі proxy.

Діагностика Vikunja, який виглядає справним

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

Репетиція оновлення має охоплювати той факт, що міграції бази даних і сумісність frontend/API потрібно тестувати до зміни версій Vikunja. Відновіть дані, виконайте міграцію та запустіть транзакцію до заміни production. Якщо публічний URL API неправильний або завантажені файли не зберігаються у volume, не стирайте дані заради успішного запуску; порівнюйте версію, змінні, mounts і доступність залежностей саме в такому порядку.

Розгорніть Vikunja у Dockup, не втрачаючи меж

Dockup може відповідати за замінні компоненти платформи: спрямувати трафік на порт 3456, видати домен і сертифікат, передати секрети, підключити постійне сховище та з’єднати Vikunja з керованими або приватно підключеними сервісами. Це можна зробити на інфраструктурі Dockup або на підключеному вами сервері.

Критерії готовності Vikunja залишаються явними. Після one-click deployment задайте VIKUNJA_SERVICE_PUBLICURL точному HTTPS origin, підключіть і перевірте Postgres або MySQL і SMTP для production-команд, а потім виконайте цей сценарій: створіть проєкт, завдання, вкладення й нагадування, перемістіть завдання на дошці та перевірте подію в календарі й сповіщення. Такий розподіл є навмисним: Dockup усуває повторюване налаштування інфраструктури, але не робить вигляд, що ролі в застосунку, облікові дані провайдера чи політика відновлення визначаються самі собою.

Часті запитання

Що потрібно Vikunja для production-розгортання?

Маршрутизуйте контейнер Vikunja на порту 3456 через один HTTPS origin. Мережева вимога для допоміжних сервісів — Postgres або MySQL і SMTP для production-команд. Не вважайте Vikunja готовим, доки не зможете створити проєкт, завдання, вкладення й нагадування, перемістити завдання на дошці та перевірити подію в календарі й сповіщення.

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

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

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

Використовуйте HTTPS для публічного Vikunja origin, а порт 3456 залиште у внутрішньому маршруті. Правильно застосуйте налаштування Vikunja: задайте VIKUNJA_SERVICE_PUBLICURL точному HTTPS origin. Для Vikunja HTTPS захищає облікові дані або вміст користувачів під час передавання та забезпечує узгоджену поведінку клієнта, чутливу до origin.

Як тестувати оновлення Vikunja?

Відновіть поточний стан Vikunja в ізольованому розгортанні, застосуйте candidate version і повторіть acceptance transaction. Будьте особливо уважні, оскільки міграції бази даних і сумісність frontend/API потрібно тестувати до зміни версій Vikunja. Зберігайте попередній образ Vikunja, доки не зрозумієте межі міграції даних і rollback.