Usage scenarios | On-Premise | 2GIS Documentation

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.

  1. 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: /
    
  2. 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.25.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.25.0
      
  1. 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: /
    
  2. 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.25.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.25.0
      
  1. 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: /
    
  2. 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.

  1. 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: /
    
  2. 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.

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

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.25.0 --apps-to-registry

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:

  1. 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)
    
  2. Download a required security certificate.

  3. 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.