diff --git a/ru/personal-domain-ya-cloud.md b/ru/personal-domain-ya-cloud.md new file mode 100644 index 0000000..b76d6ee --- /dev/null +++ b/ru/personal-domain-ya-cloud.md @@ -0,0 +1,191 @@ +# Настройка личного домена и его проксирование. + +## Создание репозитория в Diplodoc + +Быстрый старт («Quick Start») — сервис, который поможет создать репозиторий и привязать его к внешнему сервису Diplodoc. + +Для создания базовой документации: + +1. Откройте [Быстрый старт](https://diplodoc.com/quickstart/). +1. В шаге №1 авторизуйтесь в Github. +1. В шаге №2 нажмите **Создать** и создайте репозиторий в Github. В результате будет создан проект с именем «diplodoc-example», предзаполненный командой Diplodoc. +1. В шаге №3 нажмите **Создать** и создайте проект в Diplodoc. +1. После выполнения пошаговой инструкции вы получите сообщение: + + ``` + Ключи от каталога с документацией в S3. + Идентификатор ключа: + *********************** + Секретный ключ: + *********************** + + Сохраните идентификатор и ключ. После закрытия диалога значение ключа будет недоступно. Ключ будет добавлен в созданный репозиторий автоматически. + ``` + +1. Дождитесь завершения релиза, проект будет доступен по ссылке в шаге №3 на странице [Быстрого старта](https://diplodoc.com/quickstart). + +## Подготовка Yandex Cloud для привязки домена + +### Создание API-шлюза + +1. Зарегистрируйте домен (можно воспользоваться [доменным регистратором](https://yandex.ru/search/?text=доменнный+регистратор)). +1. Авторизуйтесь или создайте аккаунт в [Yandex Cloud](https://yandex.cloud/). + + {% note warning %} + + На странице [Биллинг](https://billing.yandex.cloud/accounts) убедитесь, что у вас подключен [платежный аккаунт](https://yandex.cloud/ru/docs/billing/concepts/billing-account) и находится в статусе `ACTIVE` или `TRIAL_ACTIVE`. Если платежного аккаунта нет, [создайте его](https://yandex.cloud/ru/docs/billing/quickstart/#create_billing_account). + + {% endnote %} + +1. Перейдите в [консоль Yandex Cloud](https://console.yandex.cloud/folders/). +1. Откройте **Все сервисы** → **API Gateway**. + + {% note info %} + + API Gateway — упрощенный сервер в Yandex Cloud, который позволяет обслуживать внешние запросы. Настраивается с помощью OpenAPI спецификации. + + {% endnote %} + +1. Нажмите кнопку **Создать API-шлюз**. + +1. Заполните поля **Имя\*** и описание. Поле со звездочкой обязательно для заполнения. + +1. В поле **Сеть** выберите `default` или свой вариант. + +1. Заполните поле **Спецификация**: можно воспользоваться своей OpenAPI спецификацией или примером. + + {% cut "Пример OpenAPI спецификации" %} + + {% note warning %} + + Вы можете использовать пример OpenAPI спецификации, но не забудьте изменить некоторые важные параметры, такие как: адрес внешнего домена или путь, на который должна проксироваться документация. + + {% endnote %} + + #### OpenAPI Спецификация + + ``` + openapi: 3.0.0 + info: + title: Proxy Example + version: 1.0.0 + servers: + - url: https://d5dj3947rd2qu5g1lbak.apigw.yandexcloud.net + - url: example-for-your-domain.net + paths: + /путь/{path+}: + get: + x-yc-apigateway-integration: + headers: + x-real-host: example-for-your-domain.net + x-docs-proxy-base: docs + x-docs-project-name: diplodoc-platform--docs + http_method: get + query: + '*': '*' + type: http + url: https://diplodoc-platform--docs.viewer.diplodoc.com/{path} + parameters: + - name: path + in: path + required: false + schema: + type: string + ``` + + #### Описание параметров OpenAPI спецификации + + #| + || Параметр | Описание параметра || + || `servers` | Настройка вложенных параметров `url` раздела `servers` позволит указать, по какому адресу необходимо проксировать документацию. + Для проксирования документации на ваш домен настройте вложенные параметры: + + - Первый параметр `url` содержит адрес, на котором работает API Gateway, — оставьте значение по умолчанию. + - Для второго параметра `url` укажите внешний домен, на который нужно проксировать документацию. || + || `paths` | Содержит вложенное правило, которое позволяет конфигурировать ответ для параметра `url` из раздела `servers`. Параметр `/путь/{path+}:`, вложенный в раздел `paths`, указывает, по какому пути должна располагаться документация. + + {% note info %} + + Если вы используете пример OpenAPI спецификации, то документация будет расположена по пути `example-for-your-domain.net/docs`. + + {% endnote %}|| + + || `get` | Вложенное правило, которое обрабатывает все get-запросы. || + || `headers` | Раздел содержит служебные заголовки. Для настройки служебных заголовков: + + 1\. В параметре `x-real-host:` укажите адрес домена. + 2\. В параметре `x-docs-proxy-base:` укажите каталог, на котором будет размещаться документация. + 3\. В параметре `x-docs-project-name:`укажите название проекта.|| + || `url` | Параметр, вложенный в правило `get`, содержит адрес, на который перенаправляется документация. + + {% note info %} + + Если вы используете пример OpenAPI спецификации, то документация будет перенаправляться на домен диплодока. + + {% endnote %}|| + + || `parameters` | Раздел обрабатывает параметр `path` по заданному правилу. || + |# + + {% note warning %} + + Для размещения в корне домена в OpenAPI-конфигурации измените: + + 1. У параметра `x-docs-proxy-base` значение на `' '`. + 1. У параметра `paths:` значение на `{path+}:`. + + {% endnote %} + + {% endcut %} + +1. Нажмите **Создать**. +1. Если платежный аккаунт не привязан, нажмите **Привязать**. +1. В результате должен появиться API-шлюз со статусом `active`. +1. Теперь Yandex Cloud может проксировать документацию на свой url. +1. Чтобы заработало проксирование на внешний домен, [создайте новый или загрузите личный сертификат]((#cert-creating)). + +### Создание/загрузка сертификата {#cert-creating} + +Для создания или загрузки личного сертификата: + +1. Перейдите в [консоль](https://console.yandex.cloud/folders/). +1. Откройте **Все сервисы** → **Certificate Manager**. +1. Нажмите **Создать сертификат**. +1. На странице выберите **Добавить сертификат** → **Сертификат от Let's Encrypt**. + + {% note info %} + + Если у вас уже есть сертификат, который зарегистрирован во внешнем сервисе, вы можете использовать его, для этого в выпадающем меню выберите **Пользовательский сертификат**. + + {% endnote %} + +1. Заполните поля **Имя\*** и описание. Поле со звездочкой обязательно для заполнения. +1. Укажите **Домены\***, для которых необходимо добавить сертификат. Поле обязательно для заполнения. +1. Выберите в поле **Тип проверки** — DNS. +1. Созданный сертификат будет ожидать подтверждения со статусом `Validating`. +1. [Подтвердите](#cert-validating), что вы являетесь владельцем домена. + +### Подтверждение сертификата {#cert-validating} + +Для подтверждения прав на владение доменом: + +1. Перейдите в [консоль](https://console.yandex.cloud/folders/). +1. Откройте **Все сервисы** → **Certificate Manager**. +1. Выберите созданный или добавленный сертификат. +1. Подтвердите права на владение доменом, используя один из предложенных способов. +1. Права на владение домена подтверждены. +1. [Подключите домен](#connect-domain). + +## Привязка домена к Yandex Cloud + +### Подключение домена {#connect-domain} + +Для завершения привязки домена к Yandex Cloud: + +1. Откройте **Все сервисы** → **API Gateway**. +1. Выберите созданный API-шлюз. +1. В левом меню нажмите **домены** → **Подключить**. +1. Выберите созданный сертификат. +1. Укажите домен. +1. Нажмите **Подключить**. +1. Настройка проксирования на личный домен завершена. diff --git a/ru/toc.yaml b/ru/toc.yaml index 100ab4b..45e0715 100644 --- a/ru/toc.yaml +++ b/ru/toc.yaml @@ -33,6 +33,8 @@ items: href: about.md - name: Быстрый старт href: quickstart.md + - name: Настройка личного домена + href: personal-domain-ya-cloud.md - name: Yandex Flavored Markdown expanded: true href: index-yfm.md @@ -143,4 +145,4 @@ items: href: vacancy.md - name: Yandex Open Source Jam 2024 hidden: true - href: jam.md + href: jam.md \ No newline at end of file