Setting up a personal domain and its proxying.

Article last updated at August 11, 2026

Creating a repository in Diplodoc

The Quick Start service allows you to create a repository and link it to the external Diplodoc service.

To create basic documentation:

Open Quick Start.
In step 1, authorize in GitHub.
In step 2, click Create and create a repository in GitHub. As a result, a project named "diplodoc-example" will be created, pre-filled by the Diplodoc team.
In step 3, click Create and create a project in Diplodoc.

After completing the step-by-step instructions, you will receive a message:

Ключи от каталога с документацией в S3.
Идентификатор ключа:
***********************
Секретный ключ:
***********************

Сохраните идентификатор и ключ. После закрытия диалога значение ключа будет недоступно. Ключ будет добавлен в созданный репозиторий автоматически.

Wait for the release to complete; the project will be available via the link in step 3 on the Quick Start page.

Preparing Yandex Cloud for domain linking

Creating an API gateway

Register a domain (you can use a domain registrar).
Authorize or create an account in Yandex Cloud.

Warning

On the Billing page, make sure you have a billing account connected and it is in the ACTIVE or TRIAL_ACTIVE status. If there is no billing account, create one.
Go to the Yandex Cloud console.
Open All services → API Gateway.

Note

API Gateway is a simplified server in Yandex Cloud for handling external requests. It is configured using an OpenAPI specification.
Click the Create API gateway button.
Fill in the Name* and description fields. The field with an asterisk is required.
In the Network field, select default or your own option.

Fill in the Specification field: you can use your own OpenAPI specification or an example.

Example of an OpenAPI specification

Warning

You can use the example OpenAPI specification, but do not forget to change some important parameters, such as: the address of the external domain or the path to which the documentation should be proxied.

OpenAPI Specification

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

Description of OpenAPI specification parameters

Parameter	Parameter description
`servers`	Configuring the nested `url` parameters of the `servers` section allows you to specify the address to which the documentation should be proxied. To proxy documentation to your domain, configure the nested parameters: The first `url` parameter contains the address where the API Gateway operates — leave the default value. For the second `url` parameter, specify the external domain to which the documentation should be proxied.
`paths`	Contains a nested rule that allows configuring the response for the parameter `url` from the `servers` section. The parameter `/путь/{path+}:`, nested in the `paths` section, specifies the path where the documentation should be located. Note If you use the OpenAPI specification example, the documentation will be located at `example-for-your-domain.net/docs`.
`get`	A nested rule that handles all GET requests.
`headers`	The section contains service headers. To configure service headers: 1. In the parameter `x-real-host:` specify the domain address. 2. In the parameter `x-docs-proxy-base:` specify the directory where the documentation will be hosted. 3. In the parameter `x-docs-project-name:` specify the project name.
`url`	The parameter, nested in the `get` rule, contains the address to which the documentation is redirected. Note If you use the OpenAPI specification example, the documentation will be redirected to the Diplodoc domain.
`parameters`	The section processes the `path` parameter according to the specified rule.

Warning

To place it in the domain root, change the following in the OpenAPI configuration:

For the parameter x-docs-proxy-base, set the value to ' '.
For the parameter paths:, set the value to /{path+}:.

Click Create.
If a billing account is not linked, click Link.
As a result, an API gateway with the status active should appear.
Now Yandex Cloud can proxy the documentation to its URL.
To make proxying to an external domain work, create a new or upload a personal certificate.

Creating/uploading a certificate

To create or upload a personal certificate:

Go to the console.
Open All services → Certificate Manager.
Click Create certificate.
On the page, select Add certificate → Certificate from Let's Encrypt.

Note

If you already have a certificate registered with an external service, you can use it by selecting User certificate from the dropdown menu.
Fill in the fields Name* and description. The field with an asterisk is required.
Specify the Domains* for which the certificate needs to be added. This field is required.
In the Check type field, select DNS.
The created certificate will await confirmation with the status Validating.
Confirm that you are the domain owner.

Certificate validation

To confirm domain ownership:

Go to the console.
Open All services → Certificate Manager.
Select the created or added certificate.
Confirm domain ownership using one of the suggested methods.
Domain ownership has been confirmed.
Connect the domain.

Linking a domain to Yandex Cloud

Connecting a domain

To complete linking the domain to Yandex Cloud:

Open All services → API Gateway.
Select the created API gateway.
In the left menu, click Domains → Connect.
Select the created certificate.
Specify the domain.
Click Connect.
Setting up proxying to a personal domain is complete.