diff --git a/README.md b/README.md
index cffda46..8315e30 100644
--- a/README.md
+++ b/README.md
@@ -49,7 +49,11 @@
 sudo apt update
 sudo apt install -y docker.io docker-compose-plugin
 sudo systemctl enable --now docker
+```
 
+Если apt сообщает **`Unable to locate package docker-compose-plugin`**, см. [раздел 10 в `docs/troubleshooting.md`](docs/troubleshooting.md#10-e-unable-to-locate-package-docker-compose-plugin).
+
+```bash
 sudo mkdir -p /opt/gitea/data/gitea/conf
 sudo cp gitea/docker-compose.yml /opt/gitea/docker-compose.yml
 cd /opt/gitea
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 0ffbfe2..daf5666 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -119,3 +119,57 @@ ROOT_URL = https://git.papatramp.ru/
 ```
 
 И заголовки от HAProxy в `bk_gitea` (`X-Forwarded-Proto`, `X-Forwarded-Host`, `Host`).
+
+## 10) `E: Unable to locate package docker-compose-plugin`
+
+Команды в этом репозитории используют **Docker Compose v2** (`docker compose …`). Пакет `docker-compose-plugin` есть не на каждой установке Ubuntu: отключён репозиторий **universe**, минимальный образ, сторонняя сборка без полных источников apt.
+
+### Шаг 1: включить `universe` и обновить индекс
+
+На официальных Ubuntu Desktop/Server пакет обычно в **universe**:
+
+```bash
+sudo apt-get install -y software-properties-common
+sudo add-apt-repository universe
+sudo apt-get update
+sudo apt-get install -y docker-compose-plugin
+```
+
+Если Docker ещё не ставили: `sudo apt-get install -y docker.io` (и снова `docker-compose-plugin`).
+
+### Шаг 2: официальный репозиторий Docker (если шаг 1 не помог)
+
+Подходит для систем без нужного пакета в Ubuntu или если нужны актуальные **docker-ce** и плагины с одного источника. Полная инструкция и ключи — на [странице установки Docker Engine для Ubuntu](https://docs.docker.com/engine/install/ubuntu/).
+
+Кратко: добавляется репозиторий `download.docker.com`, затем:
+
+```bash
+sudo apt-get update
+sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+sudo systemctl enable --now docker
+```
+
+**Важно:** пакет **`docker.io`** (из Ubuntu) и метапакет **`docker-ce`** (из Docker) для демона конфликтуют: на одной машине держите что-то одно. Если уже установлен `docker.io` и менять не хотите, сначала попробуйте только **шаг 1** и отдельно `docker-compose-plugin` из того же Ubuntu; иначе перейдите на `docker-ce` по документации Docker и удалите `docker.io`.
+
+### Шаг 3: плагин вручную из релиза Compose (без apt)
+
+Если нужен только бинарник Compose v2 рядом с уже работающим `docker`:
+
+- Актуальная версия и архитектура — в [релизах compose](https://github.com/docker/compose/releases).
+- Пример для amd64 (подставьте версию и имя файла со страницы релиза):
+
+```bash
+sudo mkdir -p /usr/local/lib/docker/cli-plugins
+sudo curl -SL "https://github.com/docker/compose/releases/download/v2.XX.YY/docker-compose-linux-x86_64" \
+  -o /usr/local/lib/docker/cli-plugins/docker-compose
+sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
+docker compose version
+```
+
+Путь `…/cli-plugins/docker-compose` — стандартный для подкоманды `docker compose`.
+
+### Проверка
+
+```bash
+docker compose version
+```