Установка Vikunja на VPS: self-hosted менеджер задач с Docker, SSL и резервными копиями

Что мы настраиваем и зачем

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

В этой инструкции Vikunja будет работать на Ubuntu Server 24.04 LTS. Архитектура состоит из четырёх контейнеров: API Vikunja, веб-фронтенд, PostgreSQL 17 и Caddy 2.10. Caddy принимает соединения из интернета, автоматически получает TLS-сертификат Let’s Encrypt и проксирует запросы к Vikunja.

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

Что получится в результате

• Vikunja в Docker Compose без установки зависимостей приложения в систему.
• PostgreSQL с отдельным пользователем и постоянным Docker volume.
• Домен с HTTPS и автоматическим продлением сертификата.
• Закрытые внутренние порты: PostgreSQL и API не доступны из интернета.
• Файл с секретами, исключённый из Git и резервных копий без шифрования.
• Ежедневный зашифрованный или удалённый бэкап базы данных и конфигурации.

Self-hosted или облачный сервис

Self-hosted вариант требует дисциплины: нужно следить за обновлениями, проверять резервные копии и защищать SSH-доступ. Взамен вы получаете независимость от тарифов, лимитов пользователей и внезапного изменения условий облачного продукта.

Какой VPS-конфиг нужен под эту задачу

Vikunja сам по себе потребляет немного ресурсов. Основную память занимает PostgreSQL, а дисковое пространство расходуется на базу данных, прикреплённые файлы, Docker-образы, журналы и резервные копии. Для старта не нужен мощный сервер, но слишком маленький VPS создаст проблемы при обновлении образов и создании дампов базы.

Практичный стартовый вариант — 2 vCPU, 2 ГБ RAM, 40 ГБ NVMe и публичный IPv4-адрес. Такой конфигурации хватает для Vikunja, PostgreSQL, Caddy, ежедневного бэкапа и нескольких десятков активных пользователей. Например, можно взять VPS с указанными характеристиками или аналогичный сервер у другого провайдера.

Когда потребуется больше памяти

Увеличивайте RAM до 4–8 ГБ, если на том же хосте работают Git-сервер, Mattermost, мониторинг, CI-раннеры или другие контейнеры. PostgreSQL может использовать файловый кэш Linux, поэтому дополнительная память обычно даёт более заметный эффект, чем дополнительное число vCPU.

Когда нужен dedicated, а не VPS

Для обычной Vikunja dedicated-сервер не нужен. Он становится оправданным, если вы храните сотни гигабайт вложений, обслуживаете сотни активных пользователей, запускаете несколько тяжёлых сервисов на одном хосте или вам нужны гарантированные IOPS и выделенные CPU. В большинстве случаев проще начать с VPS и увеличить тариф без миграции приложения.

Как выбрать локацию

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

Подготовка сервера

Ниже предполагается чистый сервер с Ubuntu Server 24.04 LTS и доступом под пользователем root. Перед установкой создайте DNS-запись типа A, указывающую на IPv4-адрес сервера. В примерах используется домен tasks.example.com; замените его на свой.

Обновите систему

Сначала установите актуальные обновления безопасности и базовые утилиты.

apt update && apt upgrade -y
apt install -y curl ca-certificates gnupg ufw fail2ban unattended-upgrades nano

Перезагрузите сервер, если обновилось ядро или системные библиотеки.

reboot

Создайте отдельного пользователя

Не запускайте ежедневное администрирование от root. Создайте пользователя deploy, добавьте его в группу sudo и настройте вход по SSH-ключу.

adduser deploy
usermod -aG sudo deploy
mkdir -p /home/deploy/.ssh
chmod 700 /home/deploy/.ssh
nano /home/deploy/.ssh/authorized_keys
chmod 600 /home/deploy/.ssh/authorized_keys
chown -R deploy:deploy /home/deploy/.ssh

В файл authorized_keys вставьте ваш публичный SSH-ключ, например содержимое ~/.ssh/id_ed25519.pub на локальном компьютере. Проверьте подключение во втором окне терминала, не закрывая текущую root-сессию.

ssh deploy@SERVER_IP

Отключите парольный вход по SSH

После успешной проверки ключа создайте отдельный конфигурационный файл SSH. Это безопаснее, чем редактировать основной файл пакета.

sudo nano /etc/ssh/sshd_config.d/99-hardening.conf

PermitRootLogin no
PasswordAuthentication no
KbdInteractiveAuthentication no
PubkeyAuthentication yes
X11Forwarding no
MaxAuthTries 3

Проверьте синтаксис и перезапустите SSH-службу.

sudo sshd -t && sudo systemctl restart ssh

Настройте firewall

Открытыми должны остаться только SSH, HTTP и HTTPS. Не открывайте наружу порты PostgreSQL 5432, Vikunja API 3456 и фронтенда 80 внутри Docker.

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

Включите Fail2ban и автоматические security-обновления

Fail2ban временно блокирует IP-адреса после подозрительных попыток входа по SSH. Автоматические обновления закрывают известные уязвимости Ubuntu без ручного вмешательства.

sudo systemctl enable --now fail2ban
sudo dpkg-reconfigure -plow unattended-upgrades
sudo fail2ban-client status sshd

Перед отключением парольного входа убедитесь, что SSH-ключ работает. Потеря единственного приватного ключа без консольного доступа провайдера может заблокировать администрирование сервера.

Установка ПО — пошагово

Для развёртывания используется Docker Engine 28.x или более новый стабильный релиз и Docker Compose plugin. Образы Vikunja лучше закреплять на конкретном теге, а не использовать latest: так обновление не произойдёт случайно при очередном запуске.

Установите Docker из официального репозитория

Удалите потенциально конфликтующие пакеты, если они были установлены из стандартного репозитория Ubuntu.

sudo apt remove -y docker.io docker-compose docker-compose-v2 podman-docker containerd runc || true

Добавьте ключ и репозиторий Docker.

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update

Установите Docker Engine, CLI, Buildx и Compose plugin.

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo docker --version
sudo docker compose version

Добавьте пользователя deploy в группу Docker. После команды выйдите из SSH-сеанса и войдите снова, чтобы группа применилась.

sudo usermod -aG docker deploy
exit

Повторно подключитесь и убедитесь, что Docker доступен без sudo.

ssh deploy@SERVER_IP
docker ps

Создайте рабочую структуру

Все файлы сервиса будут храниться в /opt/vikunja. Каталог доступен пользователю deploy, но не открыт другим локальным пользователям.

sudo mkdir -p /opt/vikunja/{caddy,data,backups,scripts}
sudo chown -R deploy:deploy /opt/vikunja
chmod 750 /opt/vikunja
cd /opt/vikunja

Проверьте доступность домена

До запуска Caddy DNS-запись должна уже вести на сервер. Проверка с самого сервера покажет, какой адрес возвращает публичный DNS.

getent ahostsv4 tasks.example.com

Если отображается не IP вашего VPS, исправьте DNS и дождитесь распространения записи. Для выпуска сертификата Let’s Encrypt также должны быть доступны входящие порты 80 и 443.

Конфигурация Vikunja, Docker и SSL

Ниже используется версия Vikunja 0.24.6 как пример закреплённого стабильного тега. Перед production-развёртыванием проверьте актуальный стабильный релиз в официальных release notes Vikunja и замените значение переменной при необходимости. Не используйте непроверенный тег только потому, что он новее: сначала сделайте бэкап и протестируйте обновление.

Создайте файл с переменными окружения

Сгенерируйте два случайных секрета: пароль PostgreSQL и JWT-secret Vikunja. Пароль не должен содержать пробелы и символы, которые могут быть неправильно интерпретированы shell.

cd /opt/vikunja
openssl rand -base64 32
openssl rand -hex 32

Создайте файл .env и подставьте свои значения. Значение VIKUNJA_SERVICE_PUBLICURL обязательно должно оканчиваться на слеш.

nano /opt/vikunja/.env
chmod 600 /opt/vikunja/.env

VIKUNJA_VERSION=0.24.6
POSTGRES_DB=vikunja
POSTGRES_USER=vikunja
POSTGRES_PASSWORD=CHANGE_TO_LONG_RANDOM_DATABASE_PASSWORD
VIKUNJA_SERVICE_JWTSECRET=CHANGE_TO_LONG_RANDOM_JWT_SECRET
VIKUNJA_SERVICE_PUBLICURL=https://tasks.example.com/
VIKUNJA_SERVICE_ENABLEREGISTRATION=true
VIKUNJA_SERVICE_TIMEZONE=Europe/Moscow
VIKUNJA_SERVICE_MAXIMUMATTACHMENTSIZE=20971520
DOMAIN=tasks.example.com

Параметр VIKUNJA_SERVICE_MAXIMUMATTACHMENTSIZE задан в байтах и ограничивает размер одного вложения 20 МБ. Для файлов большего размера увеличьте лимит и учитывайте свободное место на диске. После создания первого администратора публичную регистрацию обычно отключают.

Создайте Docker Compose файл

Файл Compose создаёт изолированную сеть. Из интернета опубликованы только порты Caddy, а PostgreSQL, API и фронтенд доступны лишь контейнерам внутри сети.

nano /opt/vikunja/compose.yaml

services:
  db:
    image: postgres:17-alpine
    container_name: vikunja-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 10
    networks:
      - vikunja

  api:
    image: vikunja/api:${VIKUNJA_VERSION}
    container_name: vikunja-api
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      VIKUNJA_DATABASE_TYPE: postgres
      VIKUNJA_DATABASE_HOST: db
      VIKUNJA_DATABASE_USER: ${POSTGRES_USER}
      VIKUNJA_DATABASE_PASSWORD: ${POSTGRES_PASSWORD}
      VIKUNJA_DATABASE_DATABASE: ${POSTGRES_DB}
      VIKUNJA_DATABASE_SSLMODE: disable
      VIKUNJA_SERVICE_JWTSECRET: ${VIKUNJA_SERVICE_JWTSECRET}
      VIKUNJA_SERVICE_PUBLICURL: ${VIKUNJA_SERVICE_PUBLICURL}
      VIKUNJA_SERVICE_ENABLEREGISTRATION: ${VIKUNJA_SERVICE_ENABLEREGISTRATION}
      VIKUNJA_SERVICE_TIMEZONE: ${VIKUNJA_SERVICE_TIMEZONE}
      VIKUNJA_SERVICE_MAXIMUMATTACHMENTSIZE: ${VIKUNJA_SERVICE_MAXIMUMATTACHMENTSIZE}
    volumes:
      - vikunja_files:/app/vikunja/files
    networks:
      - vikunja

  frontend:
    image: vikunja/frontend:${VIKUNJA_VERSION}
    container_name: vikunja-frontend
    restart: unless-stopped
    depends_on:
      - api
    networks:
      - vikunja

  caddy:
    image: caddy:2.10-alpine
    container_name: vikunja-caddy
    restart: unless-stopped
    depends_on:
      - frontend
      - api
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    environment:
      DOMAIN: ${DOMAIN}
    volumes:
      - ./caddy/Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    networks:
      - vikunja

networks:
  vikunja:
    name: vikunja-network

volumes:
  postgres_data:
  vikunja_files:
  caddy_data:
  caddy_config:

Настройте Caddy

Caddy автоматически запросит сертификат Let’s Encrypt, будет продлевать его и перенаправит HTTP-трафик на HTTPS. Фронтенд получает обычные запросы, а API-запросы с префиксом /api/ направляются контейнеру Vikunja API.

nano /opt/vikunja/caddy/Caddyfile

{$DOMAIN} {
    encode zstd gzip

    @api path /api/
    reverse_proxy @api api:3456

    reverse_proxy frontend:80

    header {
        -Server
        Strict-Transport-Security "max-age=31536000; includeSubDomains"
        X-Content-Type-Options "nosniff"
        X-Frame-Options "SAMEORIGIN"
        Referrer-Policy "strict-origin-when-cross-origin"
    }

    log {
        output stdout
        format console
    }
}

cd /opt/vikunja
docker compose config --quiet

cd /opt/vikunja
docker compose pull
docker compose up -d
docker compose ps

docker compose logs --tail=100 api
docker compose logs --tail=100 caddy

curl -I https://tasks.example.com
curl -fsS https://tasks.example.com/api/v1/info

sed -i 's/VIKUNJA_SERVICE_ENABLEREGISTRATION=true/VIKUNJA_SERVICE_ENABLEREGISTRATION=false/' /opt/vikunja/.env
cd /opt/vikunja
docker compose up -d --force-recreate api

Бэкапы и обслуживание

Docker volume не является резервной копией. Он хранится на том же диске, что и работающий сервис, поэтому не защищает от удаления VPS, ошибки администратора, сбоя файловой системы или компрометации сервера. Надёжный бэкап должен быть отдельным, регулярно создаваться и периодически проверяться восстановлением.

Что необходимо резервировать

• Дамп PostgreSQL: задачи, пользователи, проекты, права доступа и настройки.
• Docker volume vikunja_files: прикреплённые к задачам файлы.
• Каталог /opt/vikunja: Compose, Caddyfile, файл .env и скрипты.
• Данные Caddy: сертификаты и состояние ACME. Они не критичны для данных Vikunja, но ускоряют восстановление.

Ниже приведён простой скрипт, который создаёт сжатый дамп базы и архивирует файлы вложений. Для долгосрочного хранения используйте restic: он шифрует данные на стороне сервера и умеет отправлять их в S3-совместимое хранилище, SFTP-репозиторий или на отдельный VPS.

Установите restic

sudo apt update
sudo apt install -y restic

Для S3-совместимого хранилища создайте файл с переменными. Не добавляйте его в Git и установите права 600.

nano /opt/vikunja/.restic-env
chmod 600 /opt/vikunja/.restic-env

export RESTIC_REPOSITORY="s3:https://s3.example.net/vikunja-backups"
export RESTIC_PASSWORD="CHANGE_TO_A_LONG_UNIQUE_BACKUP_PASSWORD"
export AWS_ACCESS_KEY_ID="S3_ACCESS_KEY"
export AWS_SECRET_ACCESS_KEY="S3_SECRET_KEY"

Инициализируйте пустой репозиторий один раз.

source /opt/vikunja/.restic-env
restic init

Создайте скрипт резервного копирования

Скрипт сначала делает согласованный дамп PostgreSQL через pg_dump, затем отправляет дамп, конфигурацию и том файлов в restic. Команда Docker временно запускает контейнер Alpine, который читает volume с вложениями только для архивирования.

nano /opt/vikunja/scripts/backup.sh
chmod 700 /opt/vikunja/scripts/backup.sh

#!/usr/bin/env bash
set -euo pipefail

APP_DIR="/opt/vikunja"
BACKUP_DIR="${APP_DIR}/backups"
DATE="$(date +%F_%H-%M-%S)"

source "${APP_DIR}/.restic-env"
mkdir -p "${BACKUP_DIR}"

cd "${APP_DIR}"

docker compose exec -T db pg_dump \
  -U "${POSTGRES_USER}" \
  -d "${POSTGRES_DB}" \
  -Fc > "${BACKUP_DIR}/vikunja_${DATE}.dump"

docker run --rm \
  -v vikunja_vikunja_files:/source:ro \
  -v "${BACKUP_DIR}:/backup" \
  alpine:3.21 \
  tar -czf "/backup/vikunja_files_${DATE}.tar.gz" -C /source .

restic backup \
  "${BACKUP_DIR}/vikunja_${DATE}.dump" \
  "${BACKUP_DIR}/vikunja_files_${DATE}.tar.gz" \
  "${APP_DIR}/compose.yaml" \
  "${APP_DIR}/.env" \
  "${APP_DIR}/caddy/Caddyfile"

restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 12 --prune

rm -f "${BACKUP_DIR}/vikunja_${DATE}.dump"
rm -f "${BACKUP_DIR}/vikunja_files_${DATE}.tar.gz"

Первый запуск сделайте вручную. Так вы сразу увидите ошибку доступа к S3, неверный пароль или проблему с именем Docker volume.

/opt/vikunja/scripts/backup.sh
source /opt/vikunja/.restic-env
restic snapshots

Настройте ежедневный запуск через cron

Запускайте бэкап ночью, когда нагрузка минимальна. Вывод отправляется в лог, который полезно периодически просматривать.

crontab -e

30 3    /opt/vikunja/scripts/backup.sh >> /opt/vikunja/backups/backup.log 2>&1

Проверка восстановления

Хотя бы раз в квартал восстановите один бэкап на тестовый VPS или в отдельный каталог. Наличие snapshots не гарантирует, что пароль репозитория сохранён, архив не повреждён, а процедура восстановления понятна в аварийной ситуации.

source /opt/vikunja/.restic-env
restic restore latest --target /tmp/vikunja-restore-test
find /tmp/vikunja-restore-test -type f | head

План обновления

Для небольшой инсталляции обновляйте Vikunja в maintenance window раз в 1–2 месяца. Сначала создайте бэкап, прочитайте changelog целевой версии, измените VIKUNJA_VERSION в .env, загрузите образы и пересоздайте контейнеры. PostgreSQL major-версию не меняйте простым изменением тега: для неё нужна отдельная процедура миграции данных.

cd /opt/vikunja
/opt/vikunja/scripts/backup.sh
nano .env
docker compose pull
docker compose up -d
docker compose logs --tail=100 api
curl -fsS https://tasks.example.com/api/v1/info

Rolling update имеет смысл при нескольких экземплярах API и отдельной базе данных. Для одного VPS достаточно короткого контролируемого перерыва: обычно интерфейс недоступен менее минуты, а риск некорректного обновления ниже.

Troubleshooting и FAQ

Почему Caddy не получает SSL-сертификат?

Проверьте, что DNS-запись A домена указывает на публичный IP сервера, а порты 80 и 443 разрешены в UFW и в сетевом firewall провайдера. Посмотрите лог командой docker compose logs caddy. Частая причина — домен проксируется через CDN с неподходящим режимом SSL или существует AAAA-запись IPv6, ведущая на другой сервер. Если IPv6 не настроен, удалите неверную AAAA-запись.

Почему интерфейс открывается, но API возвращает 502 Bad Gateway?

Код 502 означает, что Caddy не может подключиться к контейнеру API. Проверьте статусы через docker compose ps и журнал docker compose logs api. Обычно API не запускается из-за неверного пароля PostgreSQL, отсутствующего JWT-secret или незавершённой инициализации базы. Также убедитесь, что в Caddyfile указан адрес api:3456, а не localhost: контейнеры используют внутреннюю Docker-сеть.

Почему Vikunja выдаёт ошибку подключения к PostgreSQL?

Сначала выполните docker compose logs db и убедитесь, что контейнер базы имеет статус healthy. Если пароль POSTGRES_PASSWORD был изменён после первого запуска PostgreSQL, база продолжит использовать старый пароль из существующего volume. Верните прежний пароль либо создайте нового пользователя вручную внутри PostgreSQL. Не удаляйте volume базы как способ «исправить» ошибку: это удалит все задачи и пользователей.

Какой VPS-конфиг минимально подойдёт?

Для одного человека или нескольких пользователей минимально подойдёт 1 vCPU, 1 ГБ RAM и 25 ГБ SSD. Однако более практичная конфигурация — 2 vCPU, 2 ГБ RAM и 40 ГБ NVMe: на ней комфортнее выполнять обновления Docker, создавать архивы и хранить несколько дней локальных временных бэкапов. Если планируются большие вложения, сначала увеличьте диск, а затем память.

Что выбрать — VPS или dedicated для этой задачи?

Для Vikunja почти всегда достаточно VPS. Приложение не требует выделенного физического сервера, если им пользуется обычная команда до сотни человек. Dedicated имеет смысл при высоких требованиях к дисковой производительности, большом объёме файлов, совместном размещении тяжёлых сервисов или необходимости гарантированно выделенных ресурсов. Начать с VPS проще, дешевле и обычно безопаснее с точки зрения администрирования.

Почему после обновления фронтенд показывает старую версию или пустую страницу?

Сначала очистите кэш браузера или откройте сервис в приватном окне: фронтенд является статическим приложением и может кешироваться. Затем проверьте, что API и frontend используют совместимые теги Vikunja в .env. Не обновляйте только один из двух образов. Посмотрите логи фронтенда и Caddy, затем выполните docker compose pull && docker compose up -d.

Как увеличить допустимый размер вложений?

Измените параметр VIKUNJA_SERVICE_MAXIMUMATTACHMENTSIZE в файле .env. Значение указывается в байтах: например, 104857600 соответствует 100 МБ. После изменения пересоздайте API-контейнер командой docker compose up -d --force-recreate api. Проверьте свободное место через df -h; большие вложения быстро увеличивают размер Docker volume и время резервного копирования.

Можно ли перенести Vikunja на другой сервер?

Да. На новом сервере установите Docker, создайте каталог /opt/vikunja, восстановите compose.yaml, .env и Caddyfile. Затем восстановите дамп PostgreSQL в новую базу и распакуйте архив файлов в volume vikunja_vikunja_files. После переключения DNS проверьте вход, проекты и вложения. На время миграции лучше остановить старый сервис, чтобы не потерять задачи, созданные после финального бэкапа.

Выводы и следующие шаги

Теперь Vikunja работает на VPS в изолированных Docker-контейнерах, доступен по HTTPS и защищён базовыми правилами firewall. Данные задач находятся в PostgreSQL, а файлы вложений и конфигурация включены в план резервного копирования.

1. Создайте тестовые проекты, настройте права команд и отключите публичную регистрацию, если она не нужна.
2. Проверьте восстановление бэкапа на отдельной машине до того, как сервис станет критичным для работы.
3. При росте команды вынесите бэкапы в отдельное хранилище, настройте мониторинг свободного места и плановые обновления.