Как добавить приложение через панель

От пустой виртуальной машины до работающего контейнера. Если приложение уже разворачивали и нужно обновить версию — смотрите «Обновление приложения после правок в репозитории».

1. Что считается приложением

Приложение — это ваш проект на машине: один контейнер или несколько связанных (например backend и proxy из одного docker-compose.yml). У приложения есть имя (webapp, shop-api и т. п.), и все его контейнеры помечаются этим именем — по нему панель различает приложения на одной машине.

Манифест — короткое описание приложения в JSON: где лежит код (репозиторий и ветка), как его собирать и как запускать. Манифест хранится в агенте на вашей машине, никуда не отправляется. Без манифеста кнопки клонирования, сборки и запуска работать не будут.

Понадобится:

• виртуальная машина в состоянии «работает» (агент отвечает);
• адрес репозитория по HTTPS (GitHub, GitLab, Gitea, свой сервер — любой git-хостинг);
• имя ветки и имя файла-инструкции: docker-compose.yml или Dockerfile;
• если репозиторий приватный — логин и токен на чтение (как получить — в статье «Манифесты»).

2. Шаг за шагом

1. Выберите машину. Откройте «Контейнеры» и выберите свою машину в списке. Ниже появится таблица контейнеров на ней — на свежей машине она пустая, это нормально.
2. Опишите приложение. В блоке манифеста вставьте JSON. Минимальный рабочий вариант для проекта с compose-файлом:

{
  "app": "webapp",
  "repo_url": "https://github.com/acme/webapp.git",
  "branch": "main",
  "compose_file": "docker-compose.yml"
}

Имя app — строчные латинские буквы, цифры, дефис и подчёркивание, до 32 символов. Остальные варианты (приватный репозиторий, монорепозиторий, только Dockerfile, готовый образ из реестра) — в статье «Манифесты: варианты и откуда брать значения». 3. Сохраните манифест. В ответе придёт подтверждение и содержимое манифеста — здесь же видно, если какое-то поле панель не приняла. 4. Клонируйте репозиторий. В выводе будут строки git и короткий хеш коммита — по нему видно, какая версия кода загружена. Повторное нажатие не ломает: агент обновляет существующий клон до состояния ветки. 5. Соберите образ. Первая сборка может занять несколько минут: панель ждёт ответа около минуты, затем сообщает, что операция продолжается в фоне — дождитесь и нажмите «Статус приложения» или повторите «Собрать образ». 6. Запустите кнопкой «Запустить всё». Агент поднимает контейнеры приложения и помечает их именем приложения. 7. Проверьте: «Обновить список» — строки контейнеров должны быть в состоянии running; затем «Health-check» в блоке состояния приложения: агент покажет состояние каждого контейнера и, если в манифесте указан health_url, результат HTTP-запроса к приложению.

Признак успеха: в таблице контейнеров есть ваши строки в состоянии running, а «Health-check» отвечает.

3. Как открыть приложение наружу

Порт внутри контейнера и порт на машине — разные вещи. Чтобы приложение было доступно по адресу http://<адрес машины>:порт, порт нужно опубликовать. Это делается там, где описан запуск:

• проект с compose — секция ports у нужного сервиса в docker-compose.yml, например ports: ["8080:80"]; после правки нужны «Клонировать репозиторий» и «Запустить всё»;
• проект только с Dockerfile — поле run_args в манифесте, например "run_args": ["-p", "0.0.0.0:8080:80"]: порт на машине 8080, порт в контейнере 80.

Запись 127.0.0.1:8080:80 вместо 0.0.0.0:8080:80 публикует порт только внутри машины — так делают для внутренних сервисов (база данных, кэш), к которым не нужен доступ снаружи.

Если приложение не открывается по адресу, проверьте: опубликован ли порт, слушает ли приложение на 0.0.0.0 внутри контейнера (а не только 127.0.0.1) и не блокирует ли порт firewall на машине.

4. Что делает каждая кнопка

Операции с приложением (блок операций на странице «Контейнеры»):

Кнопка	Что делает
Клонировать репозиторий	скачивает ветку из repo_url в рабочий каталог приложения; для уже склонированного — обновляет до последнего коммита ветки
Собрать образ	сборка через docker compose build или docker build по указанному Dockerfile; при заданном в манифесте готовом image — загрузка его из реестра
Запустить всё	поднимает контейнеры приложения (compose-проект целиком или один контейнер); уже запущенные контейнеры, чьи настройки изменились, пересоздаются
Остановить всё	останавливает контейнеры приложения, не удаляя ни их, ни образы
Перезапустить всё	быстрый перезапуск без пересборки и пересоздания
Пересобрать	сборка заново с нуля (без кэша слоёв) и запуск с пересозданием контейнеров
Обновить образ	забирает свежую версию базового образа из реестра; для образа, который собирается на машине, ничего не меняет — нужен «Пересобрать»
Health-check	состояние контейнеров и проверка health_url с самой машины
Удалить приложение	останавливает и удаляет контейнеры приложения и связанные ресурсы compose-проекта

Операции с одним контейнером: сначала выберите строку в таблице, затем «Запустить»/«Остановить» (тронуть один сервис, не перезапуская всё приложение) или «Логи» (последние строки журнала stdout/stderr; долгий вывод панель показывает сокращённо — полный журнал всегда есть на машине).

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

5. Шаблоны манифеста и токен приватного репозитория

Чтобы не писать JSON руками, в карточке манифеста есть переключатели:

• Репозиторий: «Публичный» или «Приватный»;
• Способ сборки: «Docker Compose» или «Dockerfile».

При переключении в поле подставляется подходящий шаблон — остаётся вписать адрес репозитория и, при необходимости, ветку и подпапку. Кнопка «Показать последний манифест» показывает манифест, с которым приложение работает сейчас.

Токен приватного репозитория в манифест не пишется. Для него есть отдельная карточка: поле «Токен» и необязательное «Логин» → «Сохранить токен». Токен сохраняется на вашей машине и подставляется в адрес репозитория только на время клонирования. Панель никогда не показывает его обратно — только состояние «токен: задан». Кнопка «Удалить токен» убирает доступ.

6. Частые проблемы

Что видно	Причина и что делать
«сначала сохраните манифест»	операция запущена до сохранения: сохраните манифест и повторите
при клонировании просят логин, «Authentication failed»	приватный репозиторий без токена, просроченный токен или хостинг перенаправляет на другой домен: задайте токен в карточке токена, возьмите адрес из кнопки «Clone»
«ветка не найдена»	в репозитории основная ветка master, а в манифесте main: поправьте branch
«compose-файл не найден»	проверьте subdir (папка внутри репозитория) и compose_file (имя файла)
сборка идёт долго	подождите и нажмите «Статус приложения» или «Обновить список»
контейнер не поднимается	откройте «Логи» у этого контейнера и «Перезапустить» — обычно причина видна в журнале
«Health-check» не отвечает	проверьте порт в health_url (внутри машины удобно http://127.0.0.1:порт/) и что приложение отдаёт ответ по этому пути
приложение не открывается по адресу	не опубликован порт (раздел 3) или порт закрыт firewall на машине

7. Безопасность и хранение данных

• Манифест хранится в агенте на вашей машине в файле, доступном только root.
• Токен репозитория в ответах панели показывается только состоянием «задан», в открытом виде он есть лишь на вашей машине.
• Если токен попал в чужие руки — отзовите его на хостинге, выпустите новый и сохраните в панели.
• Все операции идут от имени root внутри вашей машины: агент не выходит за её пределы и не имеет доступа к другим машинам и к панели.