Usage scenarios

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

For more complete documentation, including all available settings, see Configuration file and Command-line arguments.

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 to S3-storage

Create configuration file dgctl-config.yaml:

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: /

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:latest \
    pull --config=/dgctl-config.yaml --version=1.32.0 --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:latest \
    pull --config=/dgctl-config.yaml --version=1.32.0

pull to file system

Create configuration file dgctl-config.yaml:

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: /

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:latest \
    pull --config=/dgctl-config.yaml --version=1.32.0 --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:latest \
    pull --config=/dgctl-config.yaml --version=1.32.0

restore to S3-storage

Create configuration file dgctl-config.yaml:

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: /

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:latest \
    restore --config=/dgctl-config.yaml --from-dir=/dgctl-source --apps-to-registry
```
  If you are using On-Premise version 1.16.0 or lower, add the --with-license-v1 argument to the end of the command and use the ``--only-appsand/or--only-data` arguments to load service images and/or its data respectively.
- 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:latest \
    restore --config=/dgctl-config.yaml --from-dir=/dgctl-source
```
  If you are using On-Premise version 1.16.0 or lower, add the --with-license-v1 argument to the end of the command and use the ``--only-appsand/or--only-data` arguments to load service images and/or its data respectively.

restore to file system

Create configuration file dgctl-config.yaml:

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: /

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 /mnt/dgctl-target:/dgctl-target \
    -v /var/run/docker.sock:/var/run/docker.sock \
    --user $(id -u):$(id -g) \
    2gis/dgctl:latest \
    restore --config=/dgctl-config.yaml --from-dir=/dgctl-source --apps-to-registry
```
  If you are using On-Premise version 1.16.0 or lower, add the --with-license-v1 argument to the end of the command and use the ``--only-appsand/or--only-data` arguments to load service images and/or its data respectively.
- 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 \
    -v /mnt/dgctl-target:/dgctl-target \
    --user $(id -u):$(id -g) \
    2gis/dgctl:latest \
    restore --config=/dgctl-config.yaml --from-dir=/dgctl-source
```
  If you are using On-Premise version 1.16.0 or lower, add the --with-license-v1 argument to the end of the command and use the ``--only-appsand/or--only-data` arguments to load service images and/or its data respectively.

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:latest \
    pull --config=/dgctl-config.yaml --version=1.32.0 --apps-to-registry

Launching a 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 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.
1. 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.