Установка Dokku на Debian 13, 12 и 11

💡 Что такое Dokku и зачем он вам — это минималистичная PaaS-платформа (Platform as a Service), которая превращает ваш сервер в собственный «мини-Heroku». Вы просто делаете git push, а Dokku сам собирает Docker-образ, запускает контейнер, настраивает Nginx и SSL. Идеально для разворачивания веб-приложений на одном сервере без лишней головной боли.

⚠️ Важное предупреждение: Dokku — это полноценная платформа, которая устанавливает Docker, настраивает Nginx, создаёт своего пользователя dokku и управляет сетевыми портами. Лучше всего выделять под него отдельный сервер (VPS). На уже работающем веб-сервере установка может конфликтовать с существующими сайтами в Nginx.

Оглавление

Предварительные требования

Прежде чем начать, убедитесь, что ваша система готова:

⚠️ ВАЖНО: Проверьте права sudo перед установкой

Если вы не уверены, есть ли у вашего пользователя права администратора, выполните в терминале:

sudo whoami

Что делает:

  • sudo — выполняет команду от имени суперпользователя
  • whoami — показывает имя текущего пользователя

Зачем: Проверяет, может ли ваш пользователь выполнять команды с правами root.

✅ Если выводит root — всё в порядке, можете продолжать.

❌ Если выводит is not in the sudoers file — сначала пройдите наше руководство по настройке sudo.

Технические требования:

ТребованиеРекомендацияПочему это важно
ОСDebian 13, 12 или 11Dokku публикует пакеты только для
этих версий
Архитектураamd64 или arm64Пакеты собираются только для этих
архитектур
Оперативная памятьНе менее 1 ГБСборка Docker-образов требует
ресурсов
ДоменWildcard DNS (*.apps.example.com)Для автоматической маршрутизации
приложений
Порты22, 80, 443 открытыSSH для git push, HTTP/HTTPS для
приложений

💡 Если нет домена: Для тестирования можно использовать sslip.io — бесплатный сервис, который превращает IP-адрес в домен. Например, 203.0.113.10.sslip.io автоматически указывает на сервер с IP 203.0.113.10.

Выбор метода установки Dokku

Dokku можно установить двумя способами. Выберите тот, который подходит вашему сценарию:

МетодЧто делаетКогда использоватьОсобенности
Официальный bootstrap-скриптСам устанавливает Docker,
Nginx и Dokku		Новый сервер, первая
установка		Самый простой метод,
всё «под ключ»
Ручная установка через APTТолько Dokku, Docker уже
должен быть		Docker уже установлен
отдельно		Для продвинутых
пользователей и
автоматизации

⚠️ Используйте только один метод на одном сервере! Bootstrap-скрипт создаёт файлы в /etc/apt/sources.list.d/dokku.list, ручной метод — /etc/apt/sources.list.d/dokku.sources. Если оставить оба, будут конфликты.

Подготовка сервера к установке Dokku

Независимо от выбранного метода, начните с общей подготовки.

Шаг 1: Обновление системы

sudo apt update
sudo apt upgrade -y

Что делает:

  • apt update — обновляет список пакетов
  • apt upgrade -y — обновляет все установленные пакеты до последних версий

Зачем: Всегда начинайте установку с обновлённой системы — это избегает конфликтов версий.

Шаг 2: Проверка версии Debian и архитектуры

. /etc/os-release
printf '%s %s\n' "$PRETTY_NAME" "$VERSION_CODENAME"
dpkg --print-architecture

Что делает: Показывает точное название и кодовое имя вашей версии Debian, а также архитектуру процессора.

Поддерживаемые значения:

  • Кодовые имена: trixie (Debian 13), bookworm (Debian 12), bullseye (Debian 11)
  • Архитектуры: amd64 (обычные ПК и серверы), arm64 (Raspberry Pi, некоторые VPS)

Шаг 3: Установка FQDN (полного доменного имени)

sudo hostnamectl set-hostname apps.example.com

Что делает: Устанавливает полное доменное имя сервера.

Зачем: Dokku требует корректного hostname для работы маршрутизации.

Проверка:

hostname -f

Ожидаемый вывод: apps.example.com (или ваш домен).

Метод 1: Установка Dokku через официальный bootstrap-скрипт (рекомендуемый)

Этот метод подходит для 90% пользователей — всё, что нужно, одна команда установит Docker, Nginx и Dokku.

Шаг 1: Установка вспомогательных утилит

sudo apt install -y ca-certificates curl jq

Что делает:

  • ca-certificates — сертификаты для HTTPS
  • curl — загрузка файлов из интернета
  • jq — парсинг JSON в командной строке (нужен для работы с API GitHub)

Шаг 2: Определение последней версии Dokku

DOKKU_VERSION="$(curl -fsSL https://api.github.com/repos/dokku/dokku/releases/latest | jq -r '.tag_name')"

Что делает: Обращается к API GitHub, находит последний релиз Dokku и сохраняет его номер (например, v0.38.5).

Что делает jq -r '.tag_name': Извлекает из JSON-ответа поле tag_name и убирает кавычки.

Шаг 3: Скачивание bootstrap-скрипта

case "$DOKKU_VERSION" in
  v[0-9]*)
    curl -fsSLo bootstrap.sh "https://dokku.com/install/${DOKKU_VERSION}/bootstrap.sh"
    ;;
  *)
    printf 'Could not resolve the latest Dokku release tag.\n' >&2
    false
    ;;
esac

Что делает: Проверяет, что версия начинается с v и цифры, затем скачивает соответствующий скрипт установки.

Шаг 4: (Опционально) Проверка существующего Docker

Если Docker уже установлен (например, вы ставили его отдельно), проверьте его версию и плагины:

if command -v docker >/dev/null 2>&1; then
  docker --version
  docker buildx version
  docker compose version
fi

Что ищем: Все три команды должны вывести версии. Если какой-то команды нет — Docker установлен не полностью.

Шаг 5: Просмотр скрипта перед запуском (рекомендуется)

less bootstrap.sh

Зачем: Всегда полезно посмотреть, что будет выполняться с правами root. Нажмите q для выхода.

Шаг 6: Запуск установки

sudo DOKKU_TAG="$DOKKU_VERSION" bash bootstrap.sh

Что делает: Запускает скрипт установки с правами суперпользователя.

Скрипт сделает:

  1. Установит Docker Engine, Buildx и Compose (если их нет)
  2. Добавит APT-репозиторий Dokku
  3. Установит пакет dokku
  4. Установит зависимости для плагинов

Ожидаемый вывод: Много строк, в конце должно быть сообщение об успешной установке.

⚠️ Важно для существующих веб-серверов: Установщик может удалить существующие виртуальные хосты из директории Nginx sites-enabled. Если у вас уже есть сайты на этом сервере — сделайте резервную копию перед установкой!

Метод 2: Ручная установка Dokku через APT (для продвинутых)

Используйте этот метод, если Docker уже установлен из официального репозитория Docker, а не через bootstrap-скрипт Dokku.

Шаг 1: Проверка Docker

docker --version
docker buildx version
docker compose version

Требование: Все три команды должны работать. Если нет — сначала установите Docker по нашей инструкции.

Шаг 2: Установка инструментов

sudo apt update
sudo apt install -y ca-certificates curl gpg

Шаг 3: Добавление GPG-ключа Dokku

curl -fsSLo dokku.asc https://packagecloud.io/dokku/dokku/gpgkey
gpg --quiet --show-keys --with-fingerprint dokku.asc

Что делаем: Скачиваем ключ подписи и смотрим его отпечаток.

Ожидаемый отпечаток:

pub   rsa4096 2018-10-08 [SCEA]
      0027 A6FC E4DE B304 104D  2D13 F1FF 6851 288B 3315
uid                      https://packagecloud.io/dokku/dokku (https://packagecloud.io/docs#gpg_signing) <support@packagecloud.io>
sudo install -m 0644 dokku.asc /usr/share/keyrings/dokku-archive-keyring.asc
rm -f dokku.asc

Что делает: Устанавливает ключ в стандартную директорию с правильными правами и удаляет временный файл.

Шаг 4: Создание APT-источника в формате DEB822

. /etc/os-release
codename="${VERSION_CODENAME:-}"
arch="$(dpkg --print-architecture)"

case "${codename}:${arch}" in
    trixie:amd64|trixie:arm64|bookworm:amd64|bookworm:arm64|bullseye:amd64|bullseye:arm64)
        printf '%s\n' \
        'Types: deb' \
        'URIs: https://packagecloud.io/dokku/dokku/debian/' \
        "Suites: ${codename}" \
        'Components: main' \
        "Architectures: ${arch}" \
        'Signed-By: /usr/share/keyrings/dokku-archive-keyring.asc' \
        | sudo tee /etc/apt/sources.list.d/dokku.sources > /dev/null
        ;;
    *)
        printf 'Dokku packages are not available for %s on %s.\n' "$codename" "$arch" >&2
        exit 1
        ;;
esac

Что делает: Проверяет, что ваша система поддерживается, и создаёт современный DEB822-файл источника.

Шаг 5: Обновление APT и установка Dokku

sudo apt update
apt-cache policy dokku

Что ищем в выводе: Строку с https://packagecloud.io/dokku/dokku/debian и вашим кодовым именем Debian.

sudo debconf-set-selections <<'EOF'
dokku dokku/vhost_enable boolean true
dokku dokku/hostname string apps.example.com
dokku dokku/nginx_enable boolean true
EOF

Что делает: Предварительно отвечает на вопросы установщика (использовать ли виртуальные хосты, какой домен, включать ли Nginx).

sudo apt install -y dokku
sudo dokku plugin:install-dependencies --core

Что делает: Устанавливает Dokku и зависимости для плагинов.

Проверка установки Dokku

После установки любым методом выполните проверки:

dokku version

Что делает: Показывает установленную версию Dokku.

Ожидаемый вывод: 0.38.5 или новее.

dokku plugin:list

Что делает: Показывает список установленных плагинов.

Ожидаемый вывод: Список из 10+ плагинов (docker-options, git, letsencrypt, nginx-vhosts и т.д.).

docker --version
docker compose version

Ожидаемый вывод: Версии Docker и Compose.

sudo systemctl is-active nginx

Ожидаемый вывод: active

Настройка Dokku после установки

Dokku установлен, но чтобы начать деплоить приложения, нужно выполнить несколько шагов.

Настройка 1: Добавление SSH-ключа для деплоя

Dokku принимает git push через SSH-пользователя dokku. Добавьте ваш публичный ключ:

sudo dokku ssh-keys:add admin < ~/.ssh/id_rsa.pub

Что делает:

  • ssh-keys:add — команда Dokku для добавления ключей
  • admin — имя ключа (может быть любым)
  • < ~/.ssh/id_rsa.pub — читает ваш публичный ключ

Если ключа нет: Создайте его командой ssh-keygen -t rsa -b 4096.

Проверка:

dokku ssh-keys:list

Настройка 2: Установка глобального домена

dokku domains:set-global apps.example.com

Что делает: Устанавливает базовый домен для всех приложений. Приложение myapp получит адрес myapp.apps.example.com.

Для тестирования без домена:

dokku domains:set-global 203.0.113.10.sslip.io

Где 203.0.113.10 — ваш публичный IP-адрес.

Проверка:

dokku domains:report --global

Настройка 3: Открытие портов в файерволе (если включён)

Проверьте статус UFW:

sudo ufw status verbose

Если статус active, откройте необходимые порты:

sudo ufw allow 22/tcp    # SSH
sudo ufw allow 80/tcp    # HTTP
sudo ufw allow 443/tcp   # HTTPS
sudo ufw reload

Зачем: Dokku использует порт 22 для git push, порты 80 и 443 для веб-трафика.

Деплой первого приложения на Dokku

Шаг 1: Создание приложения на сервере

dokku apps:create sample-app
dokku domains:set sample-app sample-app.apps.example.com

Что делает: Создаёт приложение и назначает ему домен.

Проверка:

dokku apps:list

Шаг 2: Настройка Git-удалённого репозитория на вашем компьютере

На вашем локальном компьютере (не на сервере), в директории с кодом приложения:

git remote add dokku dokku@apps.example.com:sample-app

Что делает: Добавляет удалённый репозиторий Dokku в ваш локальный Git.

Шаг 3: Пуш кода в Dokku

git push dokku main:master

Что делает: Отправляет код приложения в Dokku.

Что происходит после пуша:

  1. Dokku определяет тип приложения (Node.js, Python, Ruby и т.д.)
  2. Запускает сборку Docker-образа через buildpack
  3. Запускает контейнер
  4. Настраивает Nginx для маршрутизации
  5. Возвращает URL развёрнутого приложения

Ожидаемый вывод: В конце появится строка с URL: http://sample-app.apps.example.com.

Шаг 4: Проверка статуса и логов

dokku ps:report sample-app

Что делает: Показывает подробную информацию о процессе приложения (статус, PID, используемый порт).

dokku logs sample-app --tail

Что делает: Показывает логи приложения в реальном времени. Нажмите Ctrl+C для выхода.

Управление Dokku на Debian

Dokku — это не один процесс-демон, а набор команд, которые управляют Docker и Nginx.

КомандаЧто делает
dokku apps:listСписок всех приложений
dokku apps:create APPСоздать новое приложение
dokku apps:destroy APPУдалить приложение
dokku domains:report APPПоказать домены приложения
dokku ps:report APPПоказать статус процесса
dokku ps:restart APPПерезапустить приложение
dokku ps:stop APPОстановить приложение
dokku logs APP --tailПоказать логи
dokku plugin:listСписок плагинов
sudo systemctl status dockerСтатус Docker
sudo systemctl status nginxСтатус Nginx

Обновление Dokku

Dokku обновляется через APT, но из-за особенностей пакетной структуры команда немного нестандартная:

sudo apt-get update
sudo apt-get --no-install-recommends install dokku herokuish sshcommand plugn gliderlabs-sigil dokku-update dokku-event-listener

Что делает: Обновляет Dokku и все его компоненты без установки лишних зависимостей.

После обновления (если обновлялся Herokuish):

dokku ps:stop --all
sudo apt-get update
sudo apt-get --no-install-recommends install dokku herokuish sshcommand plugn gliderlabs-sigil dokku-update dokku-event-listener
dokku ps:rebuild --all

Зачем: Остановка и пересборка гарантирует, что контейнеры используют новые версии образов и buildpack’ов.

Полное удаление Dokku

⚠️ Внимание: Все операции ниже безвозвратно удаляют приложения, базы данных и все данные Dokku. Сделайте резервные копии перед удалением!

Шаг 1: Остановка приложений и очистка

dokku ps:stop --all
dokku cleanup

Что делает: Останавливает все приложения и удаляет неиспользуемые Docker-образы.

Шаг 2: Удаление пакетов

sudo apt-get purge -y dokku herokuish
sudo apt-get autoremove -y

Что делает: Удаляет пакеты Dokku и Herokuish, а также неиспользуемые зависимости.

Шаг 3: Удаление файлов репозиториев

sudo rm -f /etc/apt/sources.list.d/dokku.list
sudo rm -f /etc/apt/sources.list.d/dokku.sources
sudo rm -f /etc/apt/trusted.gpg.d/dokku.asc
sudo rm -f /usr/share/keyrings/dokku-archive-keyring.asc
sudo apt update

Шаг 4: Удаление данных Dokku

Проверьте, что будет удалено:

sudo ls -ld /home/dokku /var/lib/dokku /var/log/dokku

Удаление:

sudo rm -rf /home/dokku /var/lib/dokku /var/log/dokku

Решение типичных проблем

8.1 Ошибка: Unsupported Linux distribution при запуске bootstrap.sh

Симптом: Скрипт установки завершается с ошибкой о неподдерживаемом дистрибутиве.

Причина: Скрипт проверяет файл /etc/os-release, и ваша система не определяется как Debian 11, 12 или 13.

Пошаговое решение:

Шаг 1: Проверьте, что говорит система:

cat /etc/os-release

Что ищем: Строку ID=debian и VERSION_CODENAME (должен быть bullseye, bookworm или trixie).

Шаг 2: Если вы используете производный дистрибутив (Ubuntu, Linux Mint), официальный скрипт может не работать. Используйте ручной метод установки через APT.

8.2 Ошибка: apt-cache policy dokku не показывает пакет

Симптом: После добавления репозитория команда apt-cache policy dokku не показывает кандидата.

Причина: Источник не добавился или архитектура/кодовое имя не поддерживаются.

Пошаговое решение:

Шаг 1: Проверьте файл источника:

cat /etc/apt/sources.list.d/dokku.sources

Шаг 2: Проверьте поддержку вашей архитектуры:

dpkg --print-architecture

Поддерживаются: amd64 и arm64.

Шаг 3: Обновите APT вручную и посмотрите ошибки:

sudo apt update

8.3 Ошибка: Permission denied (publickey) при git push

Симптом: При попытке сделать git push dokku main:master появляется ошибка Permission denied (publickey).

Причина: Ваш публичный SSH-ключ не добавлен в Dokku.

Пошаговое решение:

Шаг 1: Проверьте список ключей на сервере:

dokku ssh-keys:list

Шаг 2: Добавьте ключ (на сервере):

sudo dokku ssh-keys:add admin < ~/.ssh/id_rsa.pub

Шаг 3: С локальной машины проверьте подключение:

ssh dokku@apps.example.com

Ожидаемый вывод: Должно быть приветствие Dokku, а затем закрытие соединения.

8.4 Ошибка: Приложение не отвечает по домену (502 Bad Gateway)

Симптом: При открытии браузера по адресу приложения — ошибка 502.

Причина: Контейнер приложения не запустился или упал.

Пошаговое решение:

Шаг 1: Проверьте статус приложения:

dokku ps:report sample-app

Что ищем: Строку Status: running или Status: exited.

Шаг 2: Посмотрите логи:

dokku logs sample-app --tail

Что ищем: Ошибки приложения — неправильный Procfile, приложение слушает не тот порт, не установлены зависимости.

Шаг 3: Проверьте, что Nginx работает и маршрутизирует трафик:

sudo systemctl status nginx
curl -I http://sample-app.apps.example.com

Шаг 4: Если приложение упало, перезапустите и смотрите логи:

dokku ps:restart sample-app
dokku logs sample-app --tail

8.5 Ошибка: Порт 80 уже используется (Nginx не стартует)

Симптом: После установки Nginx не запускается или Dokku не может настроить виртуальные хосты.

Причина: Другой веб-сервер (Apache, старый Nginx) уже слушает порт 80.

Пошаговое решение:

Шаг 1: Узнайте, какой процесс занимает порт 80:

sudo ss -ltnp | grep ':80 '

Шаг 2: Если это Apache:

sudo systemctl stop apache2
sudo systemctl disable apache2

Шаг 3: Если это другой Nginx:

sudo systemctl stop nginx

Шаг 4: Запустите Nginx Dokku:

sudo systemctl start nginx

8.6 Ошибка: Недостаточно памяти для сборки

Симптом: При git push процесс сборки прерывается с ошибкой «Cannot allocate memory» или «Killed».

Причина: На сервере меньше 1 ГБ ОЗУ, и процесс сборки Docker-образа убивает OOM Killer.

Пошаговое решение:

Шаг 1: Проверьте доступную память:

free -h

Шаг 2: Временно добавьте swap (если нет или мало):

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Шаг 3: Сделайте swap постоянным (добавьте в /etc/fstab):

echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Шаг 4: Попробуйте деплой снова.

Чек-лист: что проверить после установки

  • [ ] sudo whoami выводит root
  • [ ] dokku version показывает версию (например, 0.38.5)
  • [ ] dokku plugin:list показывает список плагинов
  • [ ] docker --version и docker compose version работают
  • [ ] sudo systemctl is-active nginx показывает active
  • [ ] SSH-ключ добавлен: dokku ssh-keys:list
  • [ ] Глобальный домен установлен: dokku domains:report --global
  • [ ] Порт 80 открыт (если используется UFW): sudo ufw status
  • [ ] Можно создать тестовое приложение: dokku apps:create test
  • [ ] git push работает (даже если приложение падает, пуш должен приниматься)

Заключение

Dokku успешно установлен на Debian. Теперь у вас есть собственная PaaS-платформа, на которую можно деплоить приложения одной командой git push.

Что дальше:

💡 Важно: Dokku предназначен для одного сервера и небольших проектов. Для высоконагруженных систем лучше рассмотреть Kubernetes или другие оркестраторы. Но для личных проектов, стартапов или CI/CD — Dokku идеален.

Связанные записи