# Deploya Documentation

> Deploya — хостинг статических HTML/CSS/JavaScript-проектов с CLI, Deploy API, формами, доменами и аналитикой.

## Деплой и автоматизация

- [Готовый промт для AI-агента](https://docs.deploya.ru/ai-deploy.md): один запрос для сборки, browser login и production-деплоя.
- [Deploya CLI](https://docs.deploya.ru/cli.md): npx, browser login, команды для людей, AI-агентов и CI.
- [Deploy API v1](https://docs.deploya.ru/api.md): Bearer-токены, ZIP-деплой и идемпотентность.
- [OpenAPI](https://docs.deploya.ru/openapi.json): машиночитаемая схема API.
- [Полный контекст для LLM](https://docs.deploya.ru/llms-full.txt): все инструкции одним текстом.

## Возможности сайтов

- [Частые вопросы](https://docs.deploya.ru/faq.md)
- [Решение частых проблем](https://docs.deploya.ru/troubleshooting.md)
- [Публикация сайта](https://docs.deploya.ru/deploy.md)
- [Домены и HTTPS](https://docs.deploya.ru/domains.md)
- [Версии и хранилище](https://docs.deploya.ru/versions.md)
- [Формы и заявки](https://docs.deploya.ru/forms.md)
- [Webhook и CRM](https://docs.deploya.ru/webhooks.md)


---

# Частые вопросы о Deploya

Источник: https://docs.deploya.ru/faq

## Публикация сайта

### Что можно опубликовать в Deploya?

Deploya публикует готовые статические сайты: один HTML-файл, папку, набор файлов или ZIP-архив. Можно использовать HTML, CSS, JavaScript, изображения, шрифты и другие файлы сайта, но серверный код пользователя не запускается.

Подробнее: https://docs.deploya.ru/deploy

### Как Deploya выбирает главную страницу?

Сначала Deploya ищет `index.html`. Если его нет, но в проекте только один файл `.html` или `.htm`, он становится главной страницей автоматически. Если HTML-файлов несколько, интерфейс предложит выбрать нужный.

Подробнее: https://docs.deploya.ru/deploy#main-file

### Можно ли обновить уже опубликованный сайт?

Да. Проект можно заменить целиком или загрузить только изменённые файлы поверх текущей версии. При повторном деплое через CLI или API обновляется связанный проект, а не создаётся его копия.

Подробнее: https://docs.deploya.ru/deploy#update

### Можно ли публиковать из терминала или AI-агента?

Да. Официальный Deploya CLI умеет создавать и обновлять проекты, публиковать preview, управлять доменами и версиями. Codex, Claude Code и другие агенты с доступом к терминалу могут запускать CLI после одноразового подтверждения входа в браузере.

Подробнее: https://docs.deploya.ru/ai-deploy

## Домены и HTTPS

### Получит ли сайт бесплатный адрес?

Да. После публикации сайт получает защищённый адрес вида `project.deploya.ru` или `project.deploya.online`. Поддомен можно изменить в настройках проекта, если новое имя свободно.

Подробнее: https://docs.deploya.ru/domains#deploya-domain

### Можно ли подключить собственный домен?

Да. Добавьте домен к проекту, внесите показанные в панели DNS-записи и запустите проверку. Deploya отдельно покажет состояние DNS и HTTPS.

Подробнее: https://docs.deploya.ru/domains#custom-domain

### HTTPS подключается автоматически?

Для технических поддоменов Deploya HTTPS работает автоматически. Для собственного домена сертификат выпускается после того, как DNS-записи корректно указывают на Deploya. Обновление DNS у провайдера может занять некоторое время.

Подробнее: https://docs.deploya.ru/domains#https

### Почему собственный домен не проходит проверку?

Чаще всего мешает неправильная DNS-запись, конфликтующая старая запись или ещё не завершившееся обновление DNS. Сверьте значения с инструкцией в панели, удалите конфликтующие записи и повторите проверку. DNS может обновляться до 24 часов, но обычно изменения становятся видны заметно быстрее.

Подробнее: https://docs.deploya.ru/troubleshooting#domain-dns

## Формы и заявки

### Можно ли принимать заявки со статического сайта?

Да. Добавьте к HTML-форме `data-deploya="true"`, уникальное имя и метод `POST`. После публикации заявки появятся в разделе «Формы», где их можно перемещать между этапами обработки.

Подробнее: https://docs.deploya.ru/forms

### Куда можно отправлять уведомления о заявках?

Доступны Telegram, Email и Webhook API. Для webhook можно сопоставить названия полей и включить HMAC-подпись `X-Deploya-Signature`.

Подробнее: https://docs.deploya.ru/webhooks

### Почему Deploya не видит форму?

Форма должна присутствовать в опубликованном HTML, а не создаваться только JavaScript-кодом после загрузки страницы. Проверьте `data-deploya="true"`, уникальный `name`, `method="POST"` и атрибуты `name` у полей, затем снова опубликуйте проект.

Подробнее: https://docs.deploya.ru/troubleshooting#form-not-found

## Версии и хранилище

### Сохраняются ли предыдущие версии сайта?

Да. На Free доступна 1 предыдущая версия в течение 3 дней. На Pro доступны 5 предыдущих версий в течение 30 дней, включая preview и восстановление.

Подробнее: https://docs.deploya.ru/versions

### Занимают ли старые версии место?

Да. В анализе хранилища отдельно показаны текущие публикации, старые и preview-версии, а также локальные медиа. Ненужные версии можно удалить по одной или очистить все неактуальные версии проекта.

Подробнее: https://docs.deploya.ru/versions#storage

### Что происходит при достижении лимита хранилища?

Deploya покажет, сколько места занято и какие проекты или версии расходуют квоту. Чтобы продолжить загрузку, удалите ненужные версии или медиа либо перейдите на тариф с большим общим хранилищем.

Подробнее: https://docs.deploya.ru/versions#storage

## Команды, аналитика и AI

### Можно ли работать над проектом командой?

Да, на Pro можно создавать команды, приглашать участников и управлять общими проектами. Хранилище командного проекта учитывается у владельца и не расходует личную квоту приглашённого участника.

Подробнее: https://app.deploya.ru/teams

### Какая аналитика доступна?

В проекте доступны просмотры и статистика страниц. Deploya также проверяет сайт и формирует рекомендации по качеству, SEO и критичным проблемам; расширенные возможности зависят от тарифа.

Подробнее: https://app.deploya.ru/analytics

### Что умеет Deploya AI?

Deploya AI отвечает на вопросы о публикации, доменах и SEO, помогает создать статический сайт и редактировать файлы существующего проекта. Изменения проекта сохраняются как новые версии после публикации пользователем.

Подробнее: https://app.deploya.ru/ai-chat

---

# Решение частых проблем Deploya

Источник: https://docs.deploya.ru/troubleshooting

## Страница сайта открывает ошибку 404

Симптом: Главная страница работает, но вложенный адрес или ссылка внутри сайта не открывается.

Что проверить:

- Проверьте, что нужный HTML-файл действительно опубликован и виден в дереве Assets.
- Сверьте регистр букв в имени файла и в ссылке: `Page.html` и `page.html` — разные пути.
- Для адреса `/about` добавьте `about.html` или `about/index.html` либо укажите в ссылке фактическое имя файла.
- Убедитесь, что ссылка не ведёт на локальный путь вроде `C:\...` или `file://...`.

Подробнее: https://docs.deploya.ru/deploy#paths

## После обновления видна старая версия

Симптом: Деплой завершился, но в браузере остались прежний текст, стили или изображения.

Что проверить:

- Откройте страницу проекта и убедитесь, что последняя публикация завершилась без ошибки.
- Проверьте, что загружена готовая папка сборки, например `dist`, а не исходники проекта.
- Обновите страницу без кеша или откройте адрес в приватном окне.
- При частичном обновлении проверьте точные пути изменённых файлов; при сомнении выполните полную замену проекта.

Подробнее: https://docs.deploya.ru/deploy#update

## Открывается не та главная страница

Симптом: После загрузки проекта Deploya выбрал другой HTML-файл или просит указать главный файл.

Что проверить:

- Поместите `index.html` в корень загружаемой папки или ZIP-архива.
- Не архивируйте лишнюю внешнюю папку, если внутри неё находится весь сайт.
- Если `index.html` нет и HTML-файлов несколько, выберите нужный файл в диалоге Deploya.
- Для сборщиков сначала выполните production-сборку и загружайте её результат.

Подробнее: https://docs.deploya.ru/deploy#main-file

## Собственный домен не проходит DNS-проверку

Симптом: В панели Deploya статус DNS остаётся в ожидании или показывает ошибку.

Что проверить:

- Скопируйте тип, имя и значение записи точно из инструкции конкретного домена в панели.
- Удалите старые A- или CNAME-записи для того же имени, если они указывают на другой хостинг.
- Не добавляйте `https://` и путь страницы в значение DNS-записи.
- Подождите обновления DNS у провайдера и повторите проверку в Deploya: оно может занять до 24 часов, но обычно проходит заметно быстрее.

Подробнее: https://docs.deploya.ru/domains#troubleshooting

## HTTPS собственного домена ожидает выпуска

Симптом: DNS уже подтверждён, но защищённое соединение ещё не готово.

Что проверить:

- Сначала убедитесь, что статус DNS в Deploya успешный.
- Проверьте, что для домена не осталось конфликтующих DNS-записей.
- Подождите выпуск сертификата и повторите проверку — он начинается только после подтверждения DNS.
- Если статус долго не меняется, отправьте поддержке имя проекта, домен и скриншот статусов DNS и HTTPS.

Подробнее: https://docs.deploya.ru/domains#https

## Форма не обнаружена или заявка не появилась

Симптом: Deploya не показывает форму проекта либо отправка не создаёт заявку.

Что проверить:

- Убедитесь, что тег `<form>` присутствует в исходном опубликованном HTML, а не создаётся только JavaScript-кодом.
- Добавьте форме `data-deploya="true"`, уникальный `name` и `method="POST"`.
- Добавьте уникальный атрибут `name` каждому полю, которое должно попасть в заявку.
- После изменений заново опубликуйте проект и нажмите «Проверить подключение» в разделе «Формы».

Подробнее: https://docs.deploya.ru/forms#troubleshooting

---

# Публикация сайта в Deploya

Источник: https://docs.deploya.ru/deploy

Deploya принимает один HTML-файл, папку, набор файлов или ZIP с готовым статическим сайтом. Серверный код пользователя не запускается.

## Главный файл

Deploya сначала ищет index.html. Если его нет, единственный HTML-файл выбирается автоматически. При нескольких HTML-файлах пользователь выбирает главный в интерфейсе.

## Вложенные страницы

about.html доступен как /about и /about.html, а about/index.html — как /about. Имена файлов чувствительны к регистру.

## Обновление

Полная замена публикует новый набор файлов. Частичное обновление накладывает изменённые файлы поверх текущей версии. Повторный production-деплой через CLI обновляет связанный проект.


---

# Домены и HTTPS в Deploya

Источник: https://docs.deploya.ru/domains

Каждый проект получает адрес project.deploya.ru или project.deploya.online с автоматическим HTTPS.

Для собственного домена добавьте адрес в панели проекта, скопируйте показанные DNS-записи к своему провайдеру и запустите проверку. Не добавляйте https:// или путь страницы в значение DNS.

После подтверждения DNS Deploya отдельно проверяет HTTPS и выпускает сертификат. Если проверка не проходит, удалите конфликтующие записи, дождитесь обновления DNS и повторите попытку.


---

# Версии и хранилище Deploya

Источник: https://docs.deploya.ru/versions

Каждая публикация создаёт версию проекта. На Free доступна 1 предыдущая версия в течение 3 дней. На Pro доступны 5 предыдущих версий в течение 30 дней, preview и восстановление.

Старые и preview-версии занимают место в хранилище. В анализе квоты их можно раскрыть и удалить по одной либо очистить все нетекущие версии проекта. Текущая публикация при этом остаётся доступной.


---

# Деплой сайта в Deploya через AI-агента

Источник: https://docs.deploya.ru/ai-deploy

Подходит для Codex, Claude Code, Cursor и других AI-агентов с доступом к терминалу и файлам проекта.

## Один готовый промт

```text
Открой https://docs.deploya.ru/llms.txt и следуй инструкции Deploya CLI. Сначала выполни npx @deploya-app/cli status и проверь аккаунт и существующую привязку проекта.

Собери этот проект в production-режиме, найди папку готовой статики (обычно dist или build) и задеплой её в мой аккаунт Deploya командой npx @deploya-app/cli deploy --dir <папка> --prod.

Если CLI ещё не авторизован, сначала выполни npx @deploya-app/cli login, покажи мне одноразовый код и дождись подтверждения в браузере. Не проси пароль или API-токен. После деплоя верни публичную ссылку и сообщи, какие файлы были опубликованы.
```

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

Обычный чат без доступа к терминалу не может прочитать локальные файлы или выполнить CLI-команду.


---

# Deploya CLI

Deploya CLI публикует готовые статические сайты из терминала и подходит для AI-агентов, Codex, Claude Code и CI.

## Быстрый старт без установки

Требуется Node.js 20 или новее.

```bash
npx @deploya-app/cli login
cd my-site
npx @deploya-app/cli deploy --dir dist --prod
```

При первом деплое CLI автоматически создаст проект, подберёт свободный поддомен и сохранит идентификатор в `.deploya/project.json`. Следующий запуск обновит тот же проект. CLI ищет привязку и в родительских папках, поэтому запуск из `dist` не создаст копию.

Глобальная установка необязательна:

```bash
npm install -g @deploya-app/cli
deploya login
deploya deploy --dir dist --prod
```

## Команды

- `deploya login` — открыть браузер и подключить CLI к аккаунту.
- `deploya status` — аккаунт, тариф, хранилище, остаток проектов и текущая привязка.
- `deploya whoami` — проверить текущий аккаунт и лимиты.
- `deploya projects` — показать проекты и свободные места тарифа.
- `deploya teams` — показать команды и их ID.
- `deploya link --project ID` — привязать текущую папку к существующему проекту.
- `deploya deploy --dir dist --prod` — опубликовать production-версию.
- `deploya deploy --dir dist` — создать preview существующего связанного проекта.
- `deploya project update --subdomain new-name` — изменить адрес связанного проекта без создания копии.
- `deploya project update --name "Новое имя"` — переименовать проект.
- `deploya project stop|start` — остановить или снова запустить сайт.
- `deploya stats` — просмотры и популярные страницы.
- `deploya versions list` — версии; `versions restore --version ID --yes` — восстановление.
- `deploya domains list|add|check|remove` — управление кастомными доменами и DNS-инструкции.
- `deploya project delete --yes` — безвозвратно удалить проект.
- `deploya logout` — удалить локальный токен.

Дополнительные параметры деплоя: `--name`, `--subdomain`, `--entrypoint`, `--project`, `--team`, `--json`, `--api`.

## AI и CI

AI-агент сначала выполняет `deploya status` и `deploya projects`, чтобы увидеть аккаунт и выбрать существующий проект. Для смены поддомена используется только `project update`, а не создание нового production-проекта. Команды delete, remove и restore требуют `--yes` и прямого согласия пользователя.

Если сохранённая сессия создана старой версией CLI и не имеет права `projects:write`, один раз выполните `deploya logout`, затем `deploya login`.

Для CI создайте API-токен в Deploya и передайте его секретом окружения:

```bash
DEPLOYA_TOKEN=dpl_live_... npx @deploya-app/cli deploy --dir dist --prod
```

CLI никогда не добавляет в архив `.git`, `.deploya`, `node_modules`, `.env` и файлы `.env.*`.


---

# Deploya Deploy API v1

Базовый URL: `https://app.deploya.ru/api/v1`. Авторизация: `Authorization: Bearer dpl_live_...`.

## Деплой

`POST /api/v1/deployments`, тип `multipart/form-data`:

- `archive` — обязательный ZIP с готовым статическим сайтом;
- `projectId` — идентификатор существующего проекта; без него создаётся новый;
- `name`, `subdomain`, `teamId` — необязательны при создании;
- `entrypoint` — главный HTML, по умолчанию определяется автоматически;
- `target` — `production` или `preview` (preview доступен после первого production-деплоя).

Для безопасного повтора передавайте `Idempotency-Key: <uuid>`. Один ключ в течение 24 часов возвращает тот же результат и не создаёт повторную версию.

```bash
curl -X POST https://app.deploya.ru/api/v1/deployments \
  -H "Authorization: Bearer $DEPLOYA_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "archive=@site.zip" \
  -F "name=Мой сайт" \
  -F "target=production"
```

## Управление

- `GET /me` — аккаунт, scopes, тарифные лимиты, занятое хранилище и остаток проектов;
- `GET /projects`, `GET /projects/:id`, `GET /teams` — выбор проекта и команды;
- `PATCH /projects/:id` — название, поддомен и entrypoint без создания копии;
- `PATCH /projects/:id/status`, `DELETE /projects/:id` — остановка/запуск и удаление;
- `GET /projects/:id/stats` — аналитика;
- `GET /projects/:id/versions`, `POST /projects/:id/versions/:versionId/restore` — версии;
- `GET|POST /projects/:id/domains`, проверка и удаление домена — управление доменами.

Машиночитаемая схема: https://docs.deploya.ru/openapi.json.


---

# Формы и заявки Deploya

Источник: https://docs.deploya.ru/forms

Deploya автоматически обнаруживает HTML-формы в опубликованном статическом сайте.

## Минимальная форма

```html
<form name="contact" method="POST" data-deploya="true">
  <input name="name">
  <input name="phone" type="tel">
  <button type="submit">Отправить</button>
</form>
```

Обязательны настоящий тег form, уникальный name, method="POST" и data-deploya="true". У каждого отправляемого поля должен быть name. Загрузка файлов не поддерживается.

## AJAX — рекомендуемый способ

Перехватите submit, отправьте URLSearchParams(new FormData(form)) методом POST и добавьте Accept: application/json. Content-Type должен быть application/x-www-form-urlencoded.

После публикации откройте Формы → выберите проект → Подключение → Проверить подключение. Заявки появятся во вкладке «Заявки».


---

# Webhook Deploya: JSON, подпись и CRM

Источник: https://docs.deploya.ru/webhooks

Deploya отправляет заявку методом POST на публичный HTTPS URL. Успешным считается любой HTTP-статус 200–299.

## Заголовки

```http
Content-Type: application/json
User-Agent: Deploya-Forms/1.0
X-Deploya-Signature: sha256=<hex-hmac>  # только если задан секрет
```

## Точная схема события

```json
{
  "event": "form.submitted",
  "submission": {
    "publicId": "sub_123",
    "siteId": 28,
    "formName": "contact",
    "siteName": "Мой проект",
    "siteUrl": "https://example.deploya.ru",
    "sourcePath": "/contacts",
    "createdAt": "2026-07-04T19:30:00Z",
    "payload": {
      "PHONE": "+7 999 000-00-00",
      "EMAIL": "client@example.ru"
    }
  }
}
```

payload содержит поля формы. Настроенное сопоставление меняет только их ключи, например phone → PHONE. Системные поля события не меняются.

## Проверка подписи

Вычислите HMAC-SHA256 от точных необработанных байтов HTTP-тела с тем же секретом. Сравните строку sha256=<hex> с X-Deploya-Signature через timing-safe сравнение до разбора JSON. Без секрета заголовок подписи отсутствует.

Ошибки и HTTP-коды видны в истории доставок. Неудачную доставку можно повторить вручную; повтор создаёт отдельную попытку.