Перейти к основному содержимому

Справка по команде и аргументам 2GIS CLI

Общий вид команды для запуска утилиты 2GIS CLI имеет следующий вид:

docker run --rm \
    -v <путь>:/dgctl-config.yaml \
    -v <путь>:/dgctl-source \
    -v <путь>:/dgctl-target \
    -v /var/run/docker.sock:/var/run/docker.sock \
    --user $(id -u):$(id -g) \
    2gis/dgctl:3 \
    <команда> --config=/dgctl-config.yaml <аргументы>

Где:

  • -v <путь>:/dgctl-config.yaml — монтирование конфигурационного файла 2GIS CLI.

    В качестве пути, по которому конфигурационный файл будет доступен изнутри Docker-контейнера, необходимо указать путь /dgctl-config.yaml.

  • -v <путь>:/dgctl-source — монтирование директории для хранения артефактов установки.

    В качестве пути, по которому директория будет доступна изнутри Docker-контейнера, необходимо указать путь /dgctl-source. В качестве пути, по которому она доступна снаружи, необходимо указать:

    • В режиме license с типом хранилища fs — директорию, в которую необходимо загрузить лицензию.
    • В режиме pull с типом хранилища fs — директорию, в которую необходимо загрузить артефакты.
    • В режиме restore — директорию, в которую ранее были загружены артефакты в режиме pull.

    В остальных случаях этот аргумент можно опустить.

  • -v <путь>:/dgctl-target — монтирование целевой директории для установки.

    В качестве пути, по которому директория будет доступна изнутри Docker-контейнера, необходимо указывать путь /dgctl-target.

    Этот аргумент необходим для работы в режиме restore с типом хранилища fs. В остальных случаях этот аргумент можно опустить.

  • -v /var/run/docker.sock:/var/run/docker.sock — передача сокета Docker внутрь Docker-контейнера.

    Этот аргумент используется совместно с аргументом --apps-to-registry. Если вы не планируете использовать реестр Docker, аргумент для передачи сокета можно опустить.

  • --user $(id -u):$(id -g) — запуск 2GIS CLI от имени текущего пользователя системы.

  • <команда> — команда, определяющая режим работы утилиты:

    • license — загружает лицензию с серверов 2ГИС в S3-совместимое хранилище или файловое хранилище в приватной сети. Требует доступа в интернет.
    • pull — загружает актуальные артефакты установки с серверов обновления 2ГИС. Требует доступа в интернет.
    • restore — восстанавливает артефакты установки, которые хранятся в файловой системе. Не требует доступа в интернет.
    • save — сохраняет загруженные артефакты установки из хранилища-источника в файловую систему. Не требует доступа в интернет.
    • manifest — управляет манифестами в S3-совместимом хранилище. Не требует доступа в интернет.

  • --config=/dgctl-config.yaml — путь, по которому конфигурационный файл 2GIS CLI доступен изнутри Docker-контейнера, см. аргументы для монтирования выше.

  • <аргументы> — дополнительные аргументы запуска:

    • --apps-to-registry — если аргумент указан, Docker-образы будут помещены в реестр Docker, а не в хранилище.

      Рекомендуется всегда указывать этот аргумент, так как иначе все Docker-образы будут помещены в хранилище вместе с прочими артефактами. Подробнее см. в разделе Архитектура.

      Этот аргумент используется совместно с аргументом -v /var/run/docker.sock:/var/run/docker.sock.

    • --workers — число параллельных рабочих потоков, которые выполняют загрузку данных (по умолчанию 3, максимум 8).

    • --attempt — количество попыток восстановления артефактов в случае возникновения ошибок при записи. По умолчанию 3.

    • --overwrite — если аргумент указан, существующие файлы в S3-совместимом хранилище и реестре Docker будут перезаписаны.

    • --only-apps — скачать/восстановить только образы сервисов, но не данные для них.

    • --only-data — скачать/восстановить только данные для сервисов, но не их образы.

    • --only-license — скачать/восстановить только файл с лицензией.

    • --components=<компонент1,компонент2,...,компонент-n> (только в режимах restore и save) — список компонентов, для которых необходимо выполнить команду. При этом список компонентов в конфигурационном файле игнорируется.

    • --component=<компонент> (только в режиме manifest) — компонент, для которого необходимо выполнить команду.

    • --services=<сервис-1,сервис-2,...,сервис-n> — скачать/восстановить артефакты только для указанных сервисов. Чтобы выполнить команду для отдельного сервиса, в конфигурационном файле 2GIS CLI должен быть указан его родительский компонент. Поддерживаемые сервисы:

      • Сервис лицензий: license. Сервис принадлежит компоненту core.
      • Сервис API-ключей: keys. Сервис принадлежит компоненту core.
      • Сервис сбора статистики: stat-receiver. Сервис принадлежит компоненту api-platform.
      • Карта: mapgl-js-api, tiles-api-mobile-sdk, tiles-api-raster, tiles-api-vector, tilegen-api. Сервисы принадлежат компоненту api-platform.
      • Поиск: catalog, search. Сервисы принадлежат компоненту api-platform.
      • Навигация: navi. Сервис принадлежит компоненту api-platform.
      • 2ГИС Про: pro, pro-ui. Сервисы принадлежат компоненту pro.
      • 2ГИС Ситискан: citylens. Сервис принадлежит компоненту citylens.
      • GIS-платформа: gis-platform. Сервис принадлежит компоненту gis-platform.
      • Менеджер Платформы: platform. Сервис принадлежит компоненту api-platform.

      Этот аргумент вы можете использовать вместе с --only-apps или --only-data, чтобы загрузить только образы или только данные для выбранного сервиса.

    • --version (только в режиме pull) имеет разное поведение в зависимости от версии утилиты 2GIS CLI:

      • Для версии 3: --version <компонент>:<версия> — версия компонента программного комплекса 2ГИС, которую требуется скачать (например, --version=api-platform:1.0.0). При этом список компонентов и версий в конфигурационном файле игнорируется. См. список доступных версий в разделе Релизы на странице нужного компонента.

        Чтобы указать несколько компонентов, вы можете перечислить их через запятую или использовать параметр --version несколько раз.

        Примечание

        Рекомендуется указывать эти значения в конфигурационном файле 2GIS CLI и не использовать параметр --version. Этот способ обеспечивает удобство отладки.

      • Для версии 2: --version <версия> — версия программного комплекса 2ГИС, которую требуется скачать (например, --version=1.43.0). Только для версий, выпущенных до сентября 2025 г.: см. список в разделе Предыдущие релизы.

    • --from-dir=/dgctl-source (только в режиме restore) — директория файловой системы, из которой следует восстановить артефакты установки.

      В качестве пути к директории в этом аргументе следует всегда указывать путь /dgctl-source, по которому директория доступна изнутри Docker-контейнера. Монтирование директории выполняется с помощью аргумента -v <путь>:/dgctl-source.

      Директория должна содержать файл манифеста manifests/<компонент>/latest.json, который описывает структуру папок сервисов. Наиболее простой способ создать манифест и корректную структуру папок — запустить 2GIS CLI в режиме pull, указав файловую систему в качестве хранилища.

    • --dry-run — тестовый запуск: проверка наличия необходимых файлов для запроса лицензии (в режиме license) или вычисление ожидаемого размера выгрузки (в режиме pull).

    • --generate-values (только в режиме pull) — генерация файла с параметрами конфигурации general.yaml. Чтобы записать файл в локальную файловую систему, примонтируйте директорию при запуске утилиты с помощью аргумента -v <путь>:/values. Если не указать путь, файл удалится после запуска утилиты.

    • --keep-count (только в режиме manifest) — количество последних манифестов, которые нужно сохранить при чистке данных. Подробнее см. в разделе Чистка старых данных.

    • --with-license-v1 — для корректной работы режимов license, save и restore в версиях On-Premise 1.16.0 и ниже.