Usage scenarios

Below are some examples of configuration files and command-line arguments of DGCLI.

For more complete documentation, including all available settings, see DGCLI configuration file and DGCLI command-line arguments reference.

Note:

All passwords in this section are given for illustrative purposes.

For a real deployment, it is recommended to use more strong and secure passwords.

Basic operations

"pull" mode

pull to S3 compatible storage

Create configuration file dgctl-config.yaml. For a detailed description of the available parameters, see the DGCLI configuration file description. Example:

dgctl-config.yaml

key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB
log-format: json
storage:
    type: s3
    host: artifacts.storage.local
    bucket: dgctl-store
    access-key: AKIAIOSFODNN7EXAMPLE
    secret-key: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
docker:
    registry:
        username: registry-user
        password: DOCKERregistryP@ssW0rd
        server-address: http://docker.registry.local:5000
        image-prefix: /

# For utility version 3
components:
    core:
        version: <core-version>
    api-platform:
        version: <api-platform-version>

Run one of the following commands:

To download the Docker images into the registry, and all other artifacts into the storage:

docker run --rm \
    -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
    -v /mnt/dgctl-source:/dgctl-source \
    -v /var/run/docker.sock:/var/run/docker.sock \
    --user $(id -u):$(id -g) \
    2gis/dgctl:3 \
    pull --config=/dgctl-config.yaml --apps-to-registry

To download all the artifacts including the Docker images into the storage:

docker run --rm \
    -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
    -v /mnt/dgctl-source:/dgctl-source \
    --user $(id -u):$(id -g) \
    2gis/dgctl:3 \
    pull --config=/dgctl-config.yaml

If you are using DGCLI utility version 2, additionally specify the --version parameter with the required On-Premise software suite version. For details, see DGCLI command-line arguments reference.

pull to file system

Create configuration file dgctl-config.yaml. For a detailed description of the available parameters, see the DGCLI configuration file description. Example:

dgctl-config.yaml

key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB
log-format: json
storage:
    type: fs
    directory: /dgctl-source
docker:
    registry:
        username: registry-user
        password: DOCKERregistryP@ssW0rd
        server-address: http://docker.registry.local:5000
        image-prefix: /

# For utility version 3
components:
    core:
        version: <core-version>
    api-platform:
        version: <api-platform-version>

Run one of the following commands:

To download the Docker images into the registry, and all other artifacts into the file system:

docker run --rm \
    -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
    -v /mnt/dgctl-source:/dgctl-source \
    -v /var/run/docker.sock:/var/run/docker.sock \
    --user $(id -u):$(id -g) \
    2gis/dgctl:3 \
    pull --config=/dgctl-config.yaml --apps-to-registry

To download all the artifacts including the Docker images into the file system:

docker run --rm \
    -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
    -v /mnt/dgctl-source:/dgctl-source \
    --user $(id -u):$(id -g) \
    2gis/dgctl:3 \
    pull --config=/dgctl-config.yaml

If you are using DGCLI utility version 2, additionally specify the --version parameter with the required On-Premise software suite version. For details, see DGCLI command-line arguments reference.

"restore" mode

restore to S3 compatible storage

Create configuration file dgctl-config.yaml. For a detailed description of the available parameters, see the DGCLI configuration file description. Example:

dgctl-config.yaml

key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB
log-format: json
storage:
    type: s3
    host: artifacts.storage.local
    bucket: dgctl-store
    access-key: AKIAIOSFODNN7EXAMPLE
    secret-key: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
docker:
    registry:
        username: registry-user
        password: DOCKERregistryP@ssW0rd
        server-address: http://docker.registry.local:5000
        image-prefix: /

# For utility version 3
components:
    core:
        version: <core-version>
    api-platform:
        version: <api-platform-version>

Run one of the following commands:

To upload the Docker images to the registry, and all other artifacts to the storage:

docker run --rm \
    -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
    -v /mnt/dgctl-source:/dgctl-source \
    -v /var/run/docker.sock:/var/run/docker.sock \
    --user $(id -u):$(id -g) \
    2gis/dgctl:3 \
    restore --config=/dgctl-config.yaml --from-dir=/dgctl-source --apps-to-registry

To upload all the artifacts including the Docker images to the storage:

docker run --rm \
    -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
    -v /mnt/dgctl-source:/dgctl-source \
    --user $(id -u):$(id -g) \
    2gis/dgctl:3 \
    restore --config=/dgctl-config.yaml --from-dir=/dgctl-source

If you are using On-Premise version 1.16.0 or earlier, add the --with-license-v1 argument to the end of the command and use the --only-apps and/or --only-data arguments to upload service images and/or its data, respectively.

restore to file system

Create configuration file dgctl-config.yaml. For a detailed description of the available parameters, see the DGCLI configuration file description. Example:

dgctl-config.yaml

key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB
log-format: json
storage:
    type: fs
    directory: /dgctl-target
docker:
    registry:
        username: registry-user
        password: DOCKERregistryP@ssW0rd
        server-address: http://docker.registry.local:5000
        image-prefix: /

# For utility version 3
components:
    core:
        version: <core-version>
    api-platform:
        version: <api-platform-version>

Run one of the following commands:

To upload the Docker images to the registry, and all other artifacts to the file system:

docker run --rm \
    -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
    -v /mnt/dgctl-source:/dgctl-source \
    -v /mnt/dgctl-target:/dgctl-target \
    -v /var/run/docker.sock:/var/run/docker.sock \
    --user $(id -u):$(id -g) \
    2gis/dgctl:3 \
    restore --config=/dgctl-config.yaml --from-dir=/dgctl-source --apps-to-registry

To upload all the artifacts including the Docker images to the file system:

docker run --rm \
    -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
    -v /mnt/dgctl-source:/dgctl-source \
    -v /mnt/dgctl-target:/dgctl-target \
    --user $(id -u):$(id -g) \
    2gis/dgctl:3 \
    restore --config=/dgctl-config.yaml --from-dir=/dgctl-source

If you are using On-Premise version 1.16.0 or earlier, add the --with-license-v1 argument to the end of the command and use the ``--only-appsand/or--only-data` arguments to upload service images and/or its data respectively.

"save" mode

save from S3 compatible storage

Create a configuration file dgctl-config.yaml. For a detailed description of the available parameters, see the DGCLI configuration file description. Example:

dgctl-config.yaml

 key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB
 log-format: json
 storage:
     type: s3
     host: artifacts.storage.local
     bucket: dgctl-store
     access-key: AKIAIOSFODNN7EXAMPLE
     secret-key: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
 docker:
     registry:
         username: registry-user
         password: DOCKERregistryP@ssW0rd
         server-address: http://docker.registry.local:5000
         image-prefix: /

 # For utility version 3
 components:
     core:
         version: <core-version>
     api-platform:
         version: <api-platform-version>

Run the following command to save all the artifacts to the storage:

docker run --rm \
    -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
    -v /mnt/dgctl-target:/dgctl-target \
    --user $(id -u):$(id -g) \
    2gis/dgctl:latest \
    save --config=/dgctl-config.yaml --to-dir=/dgctl-target

"license" mode

Writing license files to S3 compatible storage

Create a configuration file dgctl-config.yaml. For a detailed description of the available parameters, see the DGCLI configuration file description. Example:

dgctl-config.yaml

 key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB
 log-format: json
 storage:
     type: s3
     host: artifacts.storage.local
     bucket: dgctl-store
     access-key: AKIAIOSFODNN7EXAMPLE
     secret-key: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
 docker:
         registry:
             username: registry-user
             password: DOCKERregistryP@ssW0rd
             server-address: http://docker.registry.local:5000
             image-prefix: /

 # For utility version 3
 components:
     core:
         version: <core-version>
     api-platform:
         version: <api-platform-version>

Run the following command to save license files to the storage:

docker run --rm \
    -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
    --user $(id -u):$(id -g) \
    2gis/dgctl:latest \
    license --config=/dgctl-config.yaml

Writing license files to file system

Create a configuration file dgctl-config.yaml. For a detailed description of the available parameters, see the DGCLI configuration file description. Example:

dgctl-config.yaml

 key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB
 log-format: json
 storage:
     type: fs
     directory: /dgctl-source
 docker:
         registry:
             username: registry-user
             password: DOCKERregistryP@ssW0rd
             server-address: http://docker.registry.local:5000
             image-prefix: /

 # For utility version 3
 components:
     core:
         version: <core-version>
     api-platform:
         version: <api-platform-version>

Run the following command to save license files to the file system:

docker run --rm \
    -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
    --user $(id -u):$(id -g) \
    2gis/dgctl:latest \
    license --config=/dgctl-config.yaml

"manifest" mode

Getting manifest list

Create a configuration file dgctl-config.yaml. For a detailed description of the available parameters, see the DGCLI configuration file description. Example:

dgctl-config.yaml

 key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB
 log-format: json
 storage:
     type: s3
     host: artifacts.storage.local
     bucket: dgctl-store
     access-key: AKIAIOSFODNN7EXAMPLE
     secret-key: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
 docker:
     registry:
         username: registry-user
         password: DOCKERregistryP@ssW0rd
         server-address: http://docker.registry.local:5000
         image-prefix: /

 # For utility version 3
 components:
     core:
         version: <core-version>
     api-platform:
         version: <api-platform-version>

Run the following command to get a manifest list in the S3 compatible storage:

docker run --rm \
    -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
    --user $(id -u):$(id -g) \
    2gis/dgctl:latest \
    manifest list --component <component>

Where component is the component name for which you want to get a manifest list.

Using system certificates

If you need to launch the DGCLI utility on systems with installed custom security certificates, additional configuration is required.

Launching in Docker

To enable the certificate to work inside the Docker container with the DGCLI utility, add the following argument to all docker launch commands to establish connection between the certificate and the utility:

-v <path-to-cert>:/etc/ssl/cert.pem

Where <path-to-cert> is a path to the installed certificate.

Example of a full command to launch the DGCLI utility with a system certificate:

docker run -it \
    -v $(pwd)/RootCa_SSL_RSA/rootca_ssl_rsa2022.cer:/etc/ssl/cert.pem \
    -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
    -v /mnt/dgctl-source:/dgctl-source \
    -v /var/run/docker.sock:/var/run/docker.sock \
    --user $(id -u):$(id -g) \
    2gis/dgctl:3 \
    pull --config=/dgctl-config.yaml --apps-to-registry

If you are using DGCLI utility version 2, additionally specify the --version parameter with the required On-Premise software suite version. For details, see DGCLI command-line arguments reference.

Launching binary file

When launching a DGCLI binary file, you might get the following error:

ERRO[0004] failed to upload object: unable to put object into s3

This might indicate problems with a certificate that enables accessing the S3 compatible storage. To resolve this problem:

Make sure that the problem is indeed related to the certificate. Run the following command using S3cmd:
```
s3cmd ls s3://bucket --host https://s3.my-host.com
```
Note

Launching S3cmd requires a configuration file with credentials to access the S3 compatible storage.

If you get the following error, the problem is related to the certificate:
```
ERROR: SSL certificate verification failure: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate (_ssl.c:1007)
```
Download a required security certificate.
Install the certificate on the system:

For UNIX-like systems (Linux, macOS):
1. Launch the terminal.
2. Copy the certificate to the system certificate storage using the command below:
```
sudo cp /<path-to-cert>/sert.crt /usr/local/share/ca-certificates/
```
  Where <path-to-cert> is a path to the downloaded certificate.
3. Update the list of trusted certificates:
```
sudo update-ca-certificates
```
For Windows:
1. Open the Start menu, search for Manage computer certificates, and open the application.
2. In the storage tree on the left, select Personal → Certificates.
3. In the top toolbar, select Action → All tasks → Import.
4. Follow the steps of the Certificate Import Wizard to install the downloaded certificate.

If the certificate is installed correctly, the application will connect to the server without issues.

Basic operations​

"pull" mode​

pull to S3 compatible storage​

pull to file system​

"restore" mode​

restore to S3 compatible storage​

restore to file system​

"save" mode​

save from S3 compatible storage​

"license" mode​

Writing license files to S3 compatible storage​

Writing license files to file system​

"manifest" mode​

Getting manifest list​

Using system certificates​

Launching in Docker​

Launching binary file​

Basic operations

"pull" mode

pull to S3 compatible storage

pull to file system

"restore" mode

restore to S3 compatible storage

restore to file system

"save" mode

save from S3 compatible storage

"license" mode

Writing license files to S3 compatible storage

Writing license files to file system

"manifest" mode

Getting manifest list

Using system certificates

Launching in Docker

Launching binary file