Развёртывание Claude Code: руководство для production

Развёртывание Claude Code становится надёжным только тогда, когда агент умеет отличать «запрос принят» от «production работает корректно». Dockup предоставляет такой слой развёртывания через CLI, рассчитанный на машинных клиентов: структурированный JSON, реальные коды завершения процессов и режим --wait, который остаётся подключённым, пока развёртывание не перейдёт в конечное состояние.

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

Что нужно Claude Code перед развёртыванием в production?

Coding agent не должен начинать с угадывания имени сервиса или перехода по dashboard. Предоставьте ему чёткий и ограниченный контракт: определить точную цель, внести одно предусмотренное изменение, дождаться результата и вернуть машиночитаемые подтверждения.

Основные требования просты:

Требование	Почему это важно	Проверка
Node.js 18 или новее	Требуется пакетом CLI Dockup	node --version
Аккаунт Dockup	Владеет workspace, сервисами и базами данных	Войдите на app.dockup.ai
Git-репозиторий	Источник сборки сервиса	Проверьте URL remote и branch
API-токен	Аутентификация без участия пользователя	dockup whoami --json
Health endpoint или listening port	Определяет возможность blue-green cutover	dockup health ... --json

Определите границы production до того, как агент начнёт действовать. Claude Code может создать сервис, задать неконфиденциальную конфигурацию, запустить deploy, проверить логи и предложить rollback. Ему не следует удалять сервис, удалять базу данных или очищать конфигурацию без явного одобрения человека.

Dockup поддерживает это ограничение. Деструктивные команды отказываются выполнять операцию без --yes и возвращают структурированную ошибку needs_confirm, а не воспринимают отсутствие подтверждения как приглашение импровизировать. Более подробные правила описаны в материале защитные ограничения для AI-агентов в production.

Как установить skill Claude Code и безопасно пройти аутентификацию?

Установите CLI, установите bundled skill и убедитесь, что skill соответствует установленному binary:

npm install -g dockup-cli
dockup skill install
dockup skill status --json

Установщик записывает canonical skill в ~/.agents/skills/dockup/ и создаёт ссылку на него в директории skills Claude Code. Поскольку skill поставляется в том же npm-пакете, что и CLI, команда dockup update обновляет их одновременно. Claude Code не приходится полагаться на скопированную справку по командам, в которой могут быть описаны flags, не поддерживаемые локальным binary.

Для автономных сессий используйте токен из environment:

export DOCKUP_TOKEN="<TOKEN>"
dockup whoami --json

Успешный ответ идентифицирует аккаунт и сообщает tokenSource со значением env. Не вставляйте токен в prompt, не добавляйте его в репозиторий и не выводите в CI log. Секреты, сохранённые в Dockup, маскируются при чтении конфигурации.

Полный справочник Dockup CLI — авторитетный источник информации о доступных командах. При наличии 135 команд Claude Code должен обращаться к актуальному справочнику и packaged skill, а не полагаться на запомнившиеся flags.

Поскольку skill поставляется внутри пакета CLI, команда dockup update обновляет binary и инструкции к нему одновременно. Такое соответствие версий безопаснее, чем копирование списка команд в prompt, который будет использоваться длительное время.

Как с помощью Dockup CLI создать сервис из Git?

Сначала попросите агента определить workspace и не строить slugs на основе отображаемых имён. Существующие цели возвращаются командой:

dockup services --json

Если репозиторий ещё ни разу не развёртывался, одна транзакция может создать сервис, выполнить его deploy, дождаться завершения и связать с текущей директорией:

dockup create my-api \
  --repo https://github.com/acme/my-api \
  --project production \
  --deploy \
  --wait \
  --link \
  --json

Если в репозитории есть Dockerfile, Dockup использует его. В его отсутствие Dockup переключается на Nixpacks для автоматического определения способа сборки. Этот выбор объясняется в статье Nixpacks и Dockerfile, где также рассматривается, когда явные инструкции по сборке оправдывают затраты на сопровождение.

Перед повторной попыткой создания после прерванной сессии снова выполните dockup services --json и проверьте точную цель. Если сервис уже существует, продолжите работу с его текущим статусом вместо повторной отправки запроса create.

После связывания команды в этом репозитории могут определять цель из .dockup, однако production runbook всё равно должен содержать полное значение project/service. Discovery — это безопасная граница между неопределённым результатом предыдущего действия и новой мутацией production.

Как подготовить environment variables, базы данных и health checks?

Храните обычную конфигурацию отдельно от секретов. Claude Code может задать публичное runtime-значение и masked secret, не выводя сохранённые секреты при последующем чтении:

dockup env set NODE_ENV=production \
  -s production/my-api \
  --json

dockup env set API_KEY="$API_KEY" \
  --secret \
  -s production/my-api \
  --json

Изменения environment применяются при следующем deploy. Это сделано намеренно: запущенный контейнер сохраняет текущее process environment, пока не будет заменён. Полный рабочий процесс описан в статье environment variables и secrets.

Если приложению нужна managed-база PostgreSQL, создайте её в выбранном workspace и получите сведения о ней с помощью документированных команд для баз данных:

dockup db create --name main-db --type postgresql --json
dockup db list --json

Впоследствии private networking может предоставить сервисам и базам данных стабильные hostnames <slug>.internal внутри одного проекта. Не поручайте агенту придумывать database URL: используйте connection information, возвращённую Dockup, и сохраните её как secret.

Настройте readiness gate до первого важного production-релиза:

dockup health production/my-api \
  --path /healthz \
  --interval 5 \
  --retries 5 \
  --json

Dockup выполняет blue-green deployment без downtime и направляет трафик на новую версию только после прохождения health gate. Архитектура подробно рассматривается в статье развёртывания без downtime.

Как Claude Code выполняет deploy и подтверждает его успешность?

Используйте --wait; не позволяйте агенту интерпретировать сообщение «deployment queued» как «приложение запущено»:

dockup deploy production/my-api --wait --json

Тайм-аут ожидания по умолчанию составляет 900 секунд. При успехе команда завершается с кодом 0 и возвращает конечный статус, длительность, ID развёртывания и URL. Если сборка завершается ошибкой, команда возвращает ненулевой код и code:"deploy_failed". Если по истечении тайм-аута операция всё ещё выполняется, команда возвращает ненулевой код и code:"deploy_timeout".

Полезная инструкция для Claude Code: «Считай код завершения процесса основным результатом, а затем обобщи поля JSON». Это не позволяет использовать оптимистичные формулировки, когда платформа уже вернула ошибку.

После успешного завершения соберите три независимых сигнала:

dockup status production/my-api --json
dockup uptime production/my-api --hours 24 --json
dockup security production/my-api --json

status подтверждает состояние сервиса и последнего deploy. uptime возвращает поминутную статистику мониторинга, включая среднее время ответа и p95. security показывает результаты последнего сканирования image на CVE и проверки конфигурации. Эти проверки дополняют практики безопасности на уровне приложения, но не заменяют application tests.

Что должен делать Claude Code при сбое в production?

Разделяйте сбой сборки и сбой runtime. При неудачной сборке требуется последний build log:

dockup logs production/my-api --build --json

Если контейнер собрался, но аварийно завершает работу после запуска, нужны runtime logs:

dockup logs production/my-api --json

Чтобы наблюдать за сборкой, сохраняя машиночитаемые batches, используйте NDJSON follow mode:

dockup logs production/my-api --build -f --json

Команда останавливается, когда deploy достигает конечного состояния, и завершается с ненулевым кодом при ошибке. Claude Code может транслировать прогресс, не создавая самостоятельно polling loop.

Если текущий релиз работает некорректно и нужно повторно запустить известный предыдущий deploy, выведите историю и используйте его точный ID:

dockup deployments production/my-api -n 20 --json
dockup rollback <deploymentId> production/my-api --json

Агент должен сообщить, какой ID развёртывания он выбрал и почему. Rollback — это операционное решение, а не замена анализу причины сбоя. Сохраните build log, runtime log, код завершения и audit record, чтобы ход инцидента можно было восстановить.

Завершённый отчёт Claude Code о deploy должен содержать цель, commit или branch, ID развёртывания, конечный статус, URL, затраченное время, результат health check и все последующие риски. Такие данные превращают автономное действие в изменение production, которое можно проверить.

Определите контракт завершения для production

До начала работы включите ожидаемый контракт завершения в задачу. Полезная формулировка: развернуть связанный репозиторий в production/my-api; дождаться конечного результата; ничего не удалять, не очищать и не переносить; при ошибке вернуть код ошибки и последние 60 релевантных строк build log; при успехе вернуть status, URL, ID развёртывания, duration и подтверждение health check.

Такая формулировка задаёт Claude Code ограниченную цель и схему отчётности. Она также не позволяет агенту «услужливо» изменять несвязанную инфраструктуру при сбое релиза. Агент может предложить отдельное исправление, но production-действие остаётся привязанным к одному запросу.

Для повторяющихся релизов храните небольшую запись о релизе в репозитории или системе управления изменениями. Указывайте target, source branch, ожидаемый health path, обычный timeout и одобренное действие по восстановлению. Развёртывание Claude Code безопаснее, когда следующей сессии не приходится восстанавливать эти сведения из истории чата.

Проверьте границы аккаунта перед первой записью

Workspace — это границы владения и биллинга. Попросите Claude Code показать whoami, вывести список сервисов и назвать выбранный workspace до внесения каких-либо изменений. План Pro стоит $20 в месяц и включает $20 usage credit; это рекомендуемый платный план. Все платные планы позволяют использовать неограниченное количество workspace, баз данных и deploy, а расход CPU, RAM и диска измеряется поминутно и списывается из баланса плана.

Такая модель ценообразования не отменяет правило безопасности: перед масштабированием или созданием дополнительных ресурсов агент должен проверить usage и область действия target. В production-отчёте следует отделять тарифный план от фактического потребления ресурсов по счётчику.

Переведите workflow в production

Установите skill в той же environment, где будет работать Claude Code, проверьте аутентификацию и начните с low-risk-сервиса, health endpoint которого уже известен.

npm install -g dockup-cli
dockup skill install

Первая команда устанавливает CLI. Вторая устанавливает соответствующий Dockup skill для Claude Code и Codex. Начните бесплатно на app.dockup.ai.

FAQ

Может ли Claude Code напрямую выполнить deploy в production с помощью Dockup?

Да. Установите Dockup skill, предоставьте scoped DOCKUP_TOKEN, определите точную target project/service и выполните команду deploy с --wait и --json.

Зачем Claude Code использовать --wait?

Без --wait успешный ответ означает только, что deploy был поставлен в очередь. С --wait Dockup завершается с кодом 0 только после успешного завершения и в противном случае возвращает структурированные ошибки deploy_failed или deploy_timeout.

Видит ли Claude Code сохранённые значения секретов?

Dockup маскирует значения секретов в output. Агент может задать или заменить secret, но чтение environment configuration не возвращает сохранённое значение секрета.

Что происходит, если в репозитории нет Dockerfile?

Dockup использует Nixpacks, чтобы автоматически определить способ сборки и собрать приложение. Dockerfile из репозитория имеет приоритет, если он присутствует.

Как Claude Code может восстановиться после неудачного релиза?

Ему следует проверить build и runtime logs, вывести историю deploy и повторно запустить известный предыдущий deploy с помощью dockup rollback, используя точный ID развёртывания.