Справка по командам и аргументам 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:latest \
    <команда> --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 — восстанавливает артефакты установки, которые хранятся в файловой системе. Не требует доступа в интернет.

• --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 — скачать/восстановить только файл с лицензией.

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

    • Общие: license, keys.
    • Карта: mapgl-js-api, tiles-api-mobile-sdk, tiles-api-raster, tiles-api-vector, floors-api.
    • Поиск: catalog, search.
    • Навигация: navi.
    • Сервис аутентификации: keycloak.
    • 2ГИС Про: pro, pro-ui.
    • CityLens: citylens.
    • GIS-платформа: gis-platform.
    • Platform Manager: platform.

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

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

  • --by-manifest=<путь> (только в режиме pull) — путь к файлу манифеста, с помощью которого следует скачать артефакты установки.

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

    Наиболее простой способ создать манифест и корректную структуру папок — запустить 2GIS CLI в режиме pull, указав файловую систему в качестве хранилища.

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

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

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

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

  • --generate-values (только в режиме pull) — сгенерировать файл с параметрами конфигурации и записать его в локальной файловую систему.

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