Перейти до основного вмісту

Розгортання API Kalheon

Продакшн-деплої йдуть через GitHub Actions, воркфлоу .github/workflows/deploy.yml.

Flow​

  1. Комміт пушиться у main.
  2. GitHub Actions відкриває SSH-сесію на claude@157.180.103.168.
  3. Віддалене репо /home/claude/projects/kalheon_agents fast-forward-ається до origin/main.
  4. На сервері запускається scripts/deploy-production.sh:
    • підтягує main;
    • виконує npm ci;
    • виконує npx prisma generate;
    • виконує npm run db:migrate:deploy;
    • виконує npm run build;
    • рестартить PM2-застосунок kalheon-api;
    • smoke-тестить https://api.kalheon.cloud/health;
    • smoke-тестить https://api.kalheon.cloud/docs/json.
  5. GitHub Actions шле Telegram-сповіщення про успіх або невдачу, якщо Telegram-секрети налаштовані.

Deploy-скрипт використовує lock-файл /tmp/kalheon-api-deploy.lock, тож два деплої не можуть йти одночасно.

GitHub secrets​

Обовʼязкові:

  • DEPLOY_SSH_KEY: приватний ключ, якому дозволено деплоїти на AX43.

Рекомендовані:

  • DEPLOY_KNOWN_HOSTS: закріплений host key SSH для 157.180.103.168.

Опційні override:

  • DEPLOY_HOST: дефолт 157.180.103.168.
  • DEPLOY_PORT: дефолт 22.
  • DEPLOY_USER: дефолт claude.
  • DEPLOY_REPO_DIR: дефолт /home/claude/projects/kalheon_agents.
  • PM2_APP: дефолт kalheon-api.
  • SMOKE_HEALTH_URL: дефолт https://api.kalheon.cloud/health.
  • SMOKE_DOCS_URL: дефолт https://api.kalheon.cloud/docs/json.

Telegram-нотифікації:

  • TG_BOT_TOKEN: Telegram bot token.
  • TG_CHAT_ID: ID чату або каналу для сповіщень про деплой.

Якщо Telegram-секретів нема — деплой все одно працює і логує, що нотифікацію пропустили.

Bootstrap сервера​

Один раз на AX43, перед увімкненням обмеженого deploy-ключа:

ssh claude@157.180.103.168
cd /home/claude/projects/kalheon_agents
git fetch origin main
git checkout main
git pull --ff-only origin main
chmod +x scripts/deploy-production.sh
scripts/deploy-production.sh

Після першого успішного bootstrap — додайте deploy public key у /home/claude/.ssh/authorized_keys.

Безпечніша обмежена форма:

command="/home/claude/projects/kalheon_agents/scripts/deploy-production.sh",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-ed25519 AAAA... kalheon-deploy

Із заданою forced-command GitHub Actions з цього ключа може тільки тригерити deploy-скрипт і нічого більше.

Ручний деплой​

ssh claude@157.180.103.168
cd /home/claude/projects/kalheon_agents
DEPLOY_BRANCH=main PM2_APP=kalheon-api scripts/deploy-production.sh

Ручний rollback​

Кращий варіант — revert-комміт у main: зберігає узгодженість продакшну з git-історією і запускає той самий pipeline:

git revert <bad_commit_sha>
git push origin main

Екстрений server-side rollback, коли revert швидко зробити не можна:

ssh claude@157.180.103.168
cd /home/claude/projects/kalheon_agents
git fetch origin main
git checkout <last_good_sha>
npm ci
npx prisma generate
npm run db:migrate:deploy
npm run build
pm2 restart kalheon-api --update-env
curl -fsS https://api.kalheon.cloud/health > /dev/null
curl -fsS https://api.kalheon.cloud/docs/json > /dev/null

За замовчуванням DB-міграції йдуть тільки вперед. Якщо поганий деплой містив міграцію схеми — для rollback може знадобитись явна correcting-міграція.

Smoke-ендпоінти​

Публічні smoke-ендпоінти:

  • https://api.kalheon.cloud/health
  • https://api.kalheon.cloud/docs/json

Version-aware health-маршрут лишається доступним за адресою https://api.kalheon.cloud/api/v1/health.