Command-line arguments | On‑Premise | Urbi Documentation
On‑Premise
Maps
Search
Navigation
Urbi Pro
CityLens
On‑Premise
Account

Command-line arguments

The general example of running DGCLI is as follows:

docker run --rm \
    -v <path>:/dgctl-config.yaml \
    -v <path>:/dgctl-source \
    -v <path>:/dgctl-target \
    -v /var/run/docker.sock:/var/run/docker.sock \
    --user $(id -u):$(id -g) \
    2gis/dgctl:latest \
    <mode> --config=/dgctl-config.yaml <arguments>

Where:

  • -v <path>:/dgctl-config.yaml - mounting the configuration file.

    As the inner path (file inside the container), you must always specify /dgctl-config.yaml.

  • -v <path>:/dgctl-source - mounting the directory for storing the installation artifacts.

    As the inner path (directory inside the container), you must always specify /dgctl-source. As the outer path (directory in the host machine), you must specify:

    • in license mode with the storage type fs — directory where you want to download the license.
    • in pull mode with the storage type fs — directory where you want to download the artifacts.
    • in restore mode - directory where the artifacts where previously downloaded using the pull mode.

    In other cases, this argument can be omitted.

  • -v <path>:/dgctl-target - mounting the directory for copying the installation artifacts.

    As the inner path (directory inside the container), you must always specify /dgctl-target.

    This argument is required only in restore mode when using file system as a storage.

  • -v /var/run/docker.sock:/var/run/docker.sock - passing the Docker socket into the Docker container.

    This argument is used together with the --apps-to-registry argument. If you are not going to use the Docker Registry, the arguments for connecting to the Docker socket can be omitted.

  • --user $(id -u):$(id -g) - launching DGCLI as a current system user.

  • <mode> - one of the modes supported by DGCLI:

    • license - downloads license from On-Promise servers to S3 storage or file storage on a private network. Requires internet access.
    • pull - downloads the up-to-date installation artifacts from the update servers. Requires internet access.
    • restore - restores installation artifacts stored in the file system. Does not require internet access.
    • save - saves downloaded installation artifacts from a source storage to the file system. Does not require internet access.
    • manifest - manages manifests in the S3 storage. Does not require internet access.

  • --config=/dgctl-config.yaml - path where the configuration file is mounted in the Docker container (see mounting arguments above).

  • <arguments> - additional arguments:

    • --apps-to-registry - if this argument is specified, the Docker images will be placed into the Docker Registry and not into the storage.

      It is recommended to always use this argument, otherwise the Docker images will be placed into the storage with other artifacts. See more in the Architecture section.

      This argument is used together with -v /var/run/docker.sock:/var/run/docker.sock.

    • --workers - number of parallel worker threads which will download the data (defaults to 3, maximum is 8).

    • --attempt - number of attempts to restore the artifacts in case of write errors. Defaults to 3.

    • --overwrite - if this argument is specified, the existing files in the S3 storage and in the Docker Registry will be overwritten.

    • --only-apps - download/restore the service images only, not the data.

    • --only-data - download/restore the service data only, not the images.

    • --only-license - download/restore the license file only.

    • --services=<service-1,service-2,...,service-n> - download/restore artifacts for the specified services only.

      • Common: license, keys.
      • Map: mapgl-js-api, tiles-api-mobile-sdk, tiles-api-raster, tiles-api-vector, floors-api.
      • Search: catalog, search.
      • Navigation: navi.
      • Authentication service: keycloak.
      • Urbi Pro: pro, pro-ui.
      • CityLens: citylens.
      • GIS Platform: gis-platform.
      • Platform Manager: platform.

      This argument can be used together with --only-apps or --only-data to download only images or only data for the specified service.

    • --version=<version> (pull mode only) - the On-Premise services version to download (e.g., --version=1.0.0). See the Releases section for the list of available versions.

    • --by-manifest=<path> (pull mode only) - path to the manifest file that should be used for downloading the installation artifacts.

      Manifest path must be specified in the form that is accessible from inside the Docker container starting after the /dgctl-source directory. The directory itself must be mounted using -v <path>:/dgctl-source.

      The simplest way to create the manifest and the correct structure is to run DGCLI in the pull mode with the file system as the storage.

    • --from-dir=/dgctl-source (restore mode only) - the file system directory from which the installation artifacts should be restored.

      You must always specify /dgctl-source as the directory path. The directory must be mounted using -v <path>:/dgctl-source.

      The directory must contain a manifest file (manifests/latest.json), which describes the services' directories structure. The simplest way to create the manifest and the correct structure is to run DGCLI in the pull mode with the file system as the storage.

    • --dry-run - test launch: check if all required files for license request are present (license mode) or calculate the expected size of downloaded artifacts (pull mode).

    • --generate-values (pull mode only) - generate the general.yaml file with configuration parameters. To write the file to the local file system, mount the directory when running the utility using the -v <path>:/values argument. If the path is not specified, the file is deleted after running the utility.

    • --with-license-v1 - for license, save, and restore modes to work correctly for On-Premise versions 1.16.0 and lower.