Розгортання Claude Code: посібник для production

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

Цей посібник описує шлях репозиторію від локальної роботи до перевіреного production-релізу. Також він визначає дозволи, які має отримати Claude Code, докази, які агент повинен повернути, і момент, коли руйнівну дію має схвалити людина.

Що потрібно Claude Code перед розгортанням у production?

Coding agent не має починати з вгадування назви сервісу чи переходів dashboard. Надайте йому чіткий операційний контракт: визначити точну ціль, виконати одну передбачену зміну, дочекатися результату й повідомити машинозчитувані докази.

Базові передумови прості:

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

Визначте production-межі до того, як агент почне діяти. Claude Code може створити сервіс, налаштувати несекретну конфігурацію, запустити deploy, перевірити логи та запропонувати rollback. Він не має видаляти сервіс, вилучати базу даних або очищати конфігурацію без явного схвалення людини.

Dockup підсилює цю межу. Деструктивні команди відмовляються виконуватися без --yes і повертають структуровану помилку needs_confirm, а не сприймають відсутність підтвердження як запрошення імпровізувати. Розширені правила див. у матеріалі production guardrails for AI agents.

Як інсталювати skill Claude Code і безпечно пройти автентифікацію?

Інсталюйте CLI, інсталюйте вбудований skill і перевірте, що skill відповідає встановленому binary:

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

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

Для автономних сесій використовуйте токен із environment:

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

Успішна відповідь ідентифікує обліковий запис і повертає tokenSource зі значенням env. Не вставляйте токен у prompt, не комітьте його до репозиторію та не виводьте в CI-лог. Секретні значення, збережені в Dockup, маскуються під час повторного читання конфігурації.

Повний довідник Dockup CLI — авторитетне джерело інформації про доступні команди. Оскільки CLI має 135 команд, Claude Code має звертатися до актуального довідника та packaged skill, а не покладатися на flags, які запам’ятав.

Оскільки skill постачається всередині пакета CLI, команда dockup update одночасно оновлює executable та його інструкції. Таке узгодження версій безпечніше, ніж копіювати список команд у prompt, який довго використовується.

Як Dockup CLI створює сервіс із Git?

Спочатку попросіть агента визначити workspace і не формувати slug із display name. Наявні цілі можна отримати так:

dockup services --json

Для репозиторію, який ще жодного разу не розгортали, одна транзакція може створити сервіс, розгорнути його, дочекатися завершення та прив’язати поточну директорію:

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

Якщо репозиторій містить Dockerfile, Dockup використовує його. Якщо Dockerfile немає, Dockup використовує Nixpacks для автоматичного визначення способу збірки. Цей вибір пояснено в матеріалі Nixpacks vs Dockerfile, зокрема описано, коли явні інструкції збірки виправдовують витрати на подальше обслуговування.

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

Після прив’язування команди в цьому репозиторії можуть визначати ціль із .dockup, однак production runbook усе одно має містити повне значення project/service. Discovery — це безпечна межа між невизначеною попередньою дією та новою зміною в production.

Як підготувати environment variables, бази даних і health checks?

Зберігайте звичайну конфігурацію окремо від секретів. Claude Code може встановити публічне runtime-значення та замаскований секрет, не виводячи збережені секретні значення під час подальшого читання:

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. Це зроблено навмисно: запущений container зберігає поточне process environment, доки його не буде замінено. Повний operating pattern описано в матеріалі environment variables and secrets.

Якщо застосунку потрібна керована база даних PostgreSQL, створіть її у вибраному workspace і отримайте її дані за допомогою документованих команд для баз даних:

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

Пізніше private networking може надати сервісам і базам даних стабільні hostnames формату <slug>.internal у межах одного проєкту. Не доручайте агенту вигадувати URL бази даних: використовуйте дані підключення, повернуті Dockup, і зберігайте їх як секрет.

Налаштуйте readiness gate перед першим важливим production-релізом:

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

Dockup виконує blue-green deployment без простою й перемикає трафік на нову версію лише після проходження health gate. Архітектуру розглянуто в матеріалі zero-downtime deployments.

Як Claude Code виконує deploy і доводить його успішність?

Використовуйте --wait; не дозволяйте агенту трактувати «deployment queued» як «застосунок працює»:

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

Стандартний timeout очікування становить 900 секунд. У разі успіху команда завершується з кодом 0 і повертає кінцевий статус, тривалість, ID розгортання та URL. Якщо збірка не вдалася, команда завершується з ненульовим кодом і code:"deploy_failed". Якщо після завершення timeout операція все ще триває, команда завершується з ненульовим кодом і 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 підтверджує стан сервісу та останнього deployment. uptime повертає похвилинну статистику моніторингу, зокрема середній час відповіді та p95. security показує результати останнього сканування CVE образу та конфігурації. Ці перевірки доповнюють практики безпеки на рівні застосунку, але не замінюють application tests.

Що має робити Claude Code у разі збою production?

Розділяйте збій збірки та runtime-збій. Якщо збірка не вдалася, потрібен останній build log:

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

Якщо container успішно зібрався, але аварійно завершує роботу після запуску, потрібен runtime output:

dockup logs production/my-api --json

Щоб переглядати збірку та водночас зберігати machine-readable batches, використовуйте NDJSON follow mode:

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

Команда зупиняється, коли deployment досягає кінцевого стану, і завершується з ненульовим кодом, якщо deployment не вдався. Claude Code може передавати прогрес без створення власного polling loop.

Якщо поточний реліз працює несправно, а відомий попередній deployment потрібно запустити повторно, перегляньте історію та використайте його точний ID:

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

Агент має повідомити, який ID deployment він вибрав і чому. Rollback — це операційне рішення, а не заміна аналізу причини збою. Збережіть build log, runtime log, код завершення та audit record, щоб інцидент можна було відтворити.

Завершений звіт Claude Code про deployment має містити ціль, commit або branch, ID deployment, кінцевий статус, URL, тривалість, результат перевірки health і всі подальші ризики. Такі докази перетворюють автономну дію на production-зміну, яку можна перевірити.

Визначте production completion contract

До початку роботи додайте до завдання очікуваний completion contract. Корисний запит може бути таким: розгорнути прив’язаний репозиторій у production/my-api; дочекатися кінцевого результату; нічого не видаляти, не очищати й не передавати; у разі помилки повернути код помилки та останні 60 релевантних рядків build log; у разі успіху повернути status, URL, ID deployment, duration і health evidence.

Таке формулювання дає Claude Code обмежену ціль і схему звітування. Воно також не дозволяє агенту «допоміжно» змінювати непов’язану інфраструктуру, якщо реліз не вдався. Агент може запропонувати окреме виправлення, але production-дія залишається прив’язаною до одного запиту.

Для повторюваних релізів зберігайте невеликий release record у репозиторії або системі керування змінами. Записуйте ціль, source branch, очікуваний health path, стандартний timeout і схвалену recovery action. Розгортання Claude Code безпечніше, коли наступній сесії не потрібно відновлювати ці факти з історії chat.

Перевірте межі облікового запису перед першим записом

Workspace — це межі володіння та білінгу. Попросіть Claude Code показати whoami, перелік сервісів і вибраний workspace до внесення будь-яких змін. План Pro коштує $20 на місяць і включає $20 кредиту на використання; усі платні плани дозволяють необмежену кількість workspace, баз даних і deployment, тоді як використання CPU, RAM і диска вимірюється щохвилини та списується з балансу плану.

Ця модель ціноутворення не змінює правила безпеки: перед масштабуванням або створенням додаткових ресурсів агент має перевірити використання та область дії цілі. У production-звіті слід розрізняти план підписки та фактичне використання ресурсів із погодинною оплатою.

Виведіть workflow у production

Інсталюйте skill у тому самому середовищі, де працюватиме Claude Code, перевірте автентифікацію та почніть із сервісу з низьким ризиком, для якого 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, надайте обмежений DOCKUP_TOKEN, визначте точну ціль project/service і виконайте команду deploy з --wait та --json.

Навіщо Claude Code використовувати --wait?

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

Чи бачить Claude Code збережені секретні значення?

Dockup маскує секретні значення у виводі. Агент може встановити або замінити секрет, але читання environment configuration не повертає збережене значення секрету.

Що відбувається, якщо в репозиторії немає Dockerfile?

Dockup використовує Nixpacks, щоб автоматично визначити спосіб збірки та зібрати застосунок. Dockerfile із репозиторію має пріоритет, якщо він присутній.

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

Він має перевірити build і runtime logs, переглянути історію deployment та повторно запустити відомий попередній deployment за допомогою dockup rollback і точного ID deployment.