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.27.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.27.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.27.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.27.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.27.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):
-
Launch the terminal.
-
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.-
Update the list of trusted certificates:
sudo update-ca-certificates
For Windows:
- Open the Start menu, search for Manage computer certificates, and open the application.
- In the storage tree on the left, select Personal -> Certificates.
- In the top toolbar, select Action -> All tasks -> Import.
- 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.