# Docker

> Please note that starting March 19th 2024, we will be migrating from Quay to Docker Hub. Follow the steps below to complete the migration.

For the platform independent usage of the VGS CLI you can use our [Docker](https://docs.docker.com/get-docker/) integration. Check our official images on [Docker Hub](https://hub.docker.com/r/verygoodsecurity/cli) repository.

## Run

In order to run in Docker we recommend declaring the following `docker-compose.yaml`:

```yaml
version: '3'
services:
  cli:
    image: verygoodsecurity/cli:\$\{VERSION:-latest\}
    stdin_open: true
    tty: true
    entrypoint: bash
    ports:
      - "127.0.0.1:7745:7745"
      - "127.0.0.1:8390:8390"
      - "127.0.0.1:9056:9056"
```

Before executing any VGS CLI commands, you need to start the container in detached mode by executing:

```bash
docker-compose up -d cli
```

Run a specific version:

```bash
VERSION=<VERSION> docker-compose up -d cli
```

## Authentication

There are two options for authentication:

* Authenticate with your personal VGS account.
* Authenticate with Service Account.

### Authenticate with your personal VGS account

For this option you need to manually execute the login command:

```bash
docker-compose exec cli vgs login
```

You will see the following output:

```bash
Can not open your browser, please open this URL in your browser: https://auth.verygoodsecurity.com/...
```

Copy the URL and paste it into your browser to authenticate to VGS.

### Authenticate with Service Account

> Make sure to never store credentials in the version control system.

If you'd like to use this option, you need to create [Service Account](https://docs.verygoodsecurity.com/vault/developer-tools/service-account#create) client first.

Having credentials of the Service Account client, you can declare the following `.env` file:

```bash
VGS_CLIENT_ID=<SERVICE_ACCOUNT_CLIENT_ID>
VGS_CLIENT_SECRET=<SERVICE_ACCOUNT_CLIENT_SECRET>
```

And the `docker-compose.yaml` should look as follows:

```yaml
version: '3'
services:
  cli:
    image: verygoodsecurity/cli:\$\{VERSION:-latest\}
    stdin_open: true
    tty: true
    entrypoint: bash
    env_file:
      - .env
    ports:
      - "127.0.0.1:7745:7745"
      - "127.0.0.1:8390:8390"
      - "127.0.0.1:9056:9056"
```

Alternatively, you can set the environment variables right in the `docker-compose.yaml`:

```yaml
version: '3'
services:
  cli:
    image: quay.io/verygoodsecurity/vgs-cli:\$\{VERSION:-latest\}
    stdin_open: true
    tty: true
    environment:
      VGS_CLIENT_ID: <SERVICE_ACCOUNT_CLIENT_ID>
      VGS_CLIENT_SECRET: <SERVICE_ACCOUNT_CLIENT_SECRET>
    entrypoint: bash
    ports:
      - "127.0.0.1:7745:7745"
      - "127.0.0.1:8390:8390"
      - "127.0.0.1:9056:9056"
```

## Use

You can now use the CLI in Docker. Try to get your route configuration with the following command:

```bash
docker-compose exec cli vgs get routes --vault <VAULT_ID>
```

This command will get your route configurations in YAML format.

## Cleanup

When you finished working with the CLI you can run:

```bash
docker-compose down
```

## Next Steps

Check what else you can do. Use these guides or explore the CLI with `docker-compose exec cli vgs --help` command.

* [Commands](https://docs.verygoodsecurity.com/vault/developer-tools/vgs-cli/commands)
* [Troubleshooting](https://docs.verygoodsecurity.com/vault/developer-tools/vgs-cli/troubleshooting)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.verygoodsecurity.com/vault/developer-tools/vgs-cli/docker.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.