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

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

В этом руководстве используется один конкретный критерий готовности: создать проект, задачу, вложение и напоминание, переместить задачу на доске и проверить событие в календаре и уведомление. Каждое решение по конфигурации оценивается по этому критерию, а не по зелёному статусу контейнера.

От чего зависит Vikunja

Обозначьте вокруг Vikunja три границы: ingress к порту 3456, постоянное состояние и вспомогательные требования. Контейнер можно заменить, но для двух других компонентов нужно явно определить ответственных. Сетевой контракт Vikunja в production-среде включает Postgres или MySQL и SMTP для рабочих команд. Приватные endpoints следует размещать во внутреннем DNS, разрешать только необходимые исходящие вызовы и выдавать Vikunja service credential с ограниченными правами.

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

Volumes — только первый уровень восстановления

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

Snapshots удобны для быстрого rollback, но при потере хоста или volume необходима независимая backup-копия. Восстановите данные в пустом окружении с зафиксированным образом и проверьте, что проекты, история задач, вложения, напоминания и пользователи вернулись, а запланированное уведомление по-прежнему отправляется. Используйте persistent volumes and snapshots, чтобы разделять эти два механизма восстановления.

Защитите ценные данные Vikunja

После первого входа проверьте, что могут делать анонимный посетитель, обычный пользователь и администратор. Ошибка Vikunja, которой следует избежать, — использование неизменённого JWT secret или случайно открытая регистрация. Предусмотренная политика: использовать стабильный JWT secret, закрыть регистрацию после завершения набора пользователей и разделить обычных участников и администраторов проектов.

Сгенерируйте VIKUNJA_SERVICE_JWTSECRET как длинное случайное значение; его смена обычно делает сессии или токены недействительными, поэтому заранее спланируйте влияние на пользователей и не рассматривайте эту операцию как миграцию шифрования. Разделяйте аккаунты зависимостей и аккаунты людей, по возможности запрещайте неиспользуемый egress и ограничивайте нагрузку, связанную с трафиком вложений, запросами к базе данных, фоновыми задачами и исходящей почтой, а не только небольшим API-процессом.

Превратите smoke test Vikunja в проверку релиза

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

Запустите этот тест после замены runtime, а затем пересоберите сервис из базы данных, загруженных файлов и конфигурации. Восстановление считается успешным, если проекты, история задач, вложения, напоминания и пользователи вернулись, а запланированное уведомление по-прежнему отправляется. Сравните с предыдущим релизом измерения ресурсов для трафика вложений, запросов к базе данных, фоновых задач и исходящей почты, а не только для небольшого API-процесса, и до продвижения релиза исследуйте существенные отклонения.

Наконец, выполните контролируемую проверку сбоя: временно запретите тестовой identity доступ к Postgres или MySQL и SMTP для рабочих команд. Убедитесь, что 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 проверьте итоговые environment variables, mounts и listener. Добавьте проверенные настройки подключения к Postgres или MySQL и SMTP для рабочих команд; для приватных сервисов используйте приватные имена. Успешный запуск завершается не тогда, когда docker ps выводит Up, а когда вы можете создать проект, задачу, вложение и напоминание, переместить задачу на доске и проверить событие в календаре и уведомление.

Маршрутизируйте Vikunja, не искажая HTTPS

Не используйте для Vikunja временные и постоянные public origins. Вместо этого задайте VIKUNJA_SERVICE_PUBLICURL как точный HTTPS origin, направьте выбранное DNS-имя на route платформы и проксируйте запросы только на порт 3456.

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

Диагностируйте Vikunja, который выглядит работоспособным

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

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

Разверните Vikunja в Dockup, сохранив границы ответственности

Dockup может взять на себя заменяемые компоненты платформы: направлять трафик на порт 3456, выдавать домен и сертификат, передавать secrets, подключать persistent storage и соединять Vikunja с managed-сервисами или сервисами, подключёнными приватно. Это можно сделать на инфраструктуре Dockup или на подключённом вами сервере.

Ответственность за приёмку Vikunja остаётся явной. После one-click deployment задайте VIKUNJA_SERVICE_PUBLICURL как точный HTTPS origin, подключите и проверьте Postgres или MySQL и SMTP для рабочих команд и выполните этот сценарий: создайте проект, задачу, вложение и напоминание, переместите задачу на доске и проверьте событие в календаре и уведомление. Такое разделение намеренно: Dockup устраняет повторяющуюся настройку инфраструктуры, но не делает вид, будто роли приложения, credentials провайдеров или политика восстановления выбираются автоматически.

Часто задаваемые вопросы

Что нужно Vikunja для production-развёртывания?

Направьте контейнер Vikunja на порту 3456 через один HTTPS origin. Сетевые требования для вспомогательных сервисов — Postgres или MySQL и SMTP для рабочих команд. Не объявляйте Vikunja готовым, пока не сможете создать проект, задачу, вложение и напоминание, переместить задачу на доске и проверить событие в календаре и уведомление.

Какие данные Vikunja должны входить в backup?

Сохраняйте /app/vikunja/files и включайте базу данных, загруженные файлы и конфигурацию в единый recovery manifest. Восстановление Vikunja в чистом окружении считается успешным только тогда, когда возвращаются проекты, история задач, вложения, напоминания и пользователи, а запланированное уведомление по-прежнему отправляется.

Требуется ли Vikunja HTTPS за reverse proxy?

Используйте HTTPS для публичного origin Vikunja, а порт 3456 оставьте во внутреннем route. Корректно примените настройку Vikunja: задайте VIKUNJA_SERVICE_PUBLICURL как точный HTTPS origin. Для Vikunja HTTPS защищает credentials и пользовательский контент при передаче и обеспечивает согласованное поведение клиента, зависящее от origin.

Как тестировать обновление Vikunja?

Восстановите текущее состояние Vikunja в изолированном deployment, примените candidate version и повторите транзакцию приёмки. Уделите этому особое внимание, поскольку database migrations и совместимость frontend/API необходимо проверять до смены версии Vikunja. Не удаляйте предыдущий образ Vikunja, пока не будут понятны границы миграции данных и rollback.