diff --git a/.github/labeler.yml b/.github/labeler.yml index bd7e0104000c..9a51b7cca769 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -159,6 +159,11 @@ area/accounts: - any-glob-to-any-file: - content/manuals/accounts/** +area/copilot: + - changed-files: + - any-glob-to-any-file: + - content/manuals/copilot/** + hugo: - changed-files: - any-glob-to-any-file: diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt index 036c9e833475..933d166bf315 100644 --- a/_vale/config/vocabularies/Docker/accept.txt +++ b/_vale/config/vocabularies/Docker/accept.txt @@ -99,6 +99,7 @@ OCI OTel Okta PAT +PEM Postgres PowerShell Python @@ -140,6 +141,7 @@ WSL Wasm Windows WireMock +Zscaler Zsh [Bb]uildx [Cc]odenames? diff --git a/content/guides/zscaler/index.md b/content/guides/zscaler/index.md new file mode 100644 index 000000000000..56c35463d534 --- /dev/null +++ b/content/guides/zscaler/index.md @@ -0,0 +1,141 @@ +--- +title: Using Docker with Zscaler +tags: [networking, admin] +summary: | + This guide explains how to embed Zscaler’s root certificate into Docker + images, allowing containers to operate securely with Zscaler proxies and + avoid SSL errors. +params: + time: 10 minutes +--- + +In many corporate environments, network traffic is intercepted and monitored +using HTTPS proxies, such as Zscaler. While Zscaler ensures security compliance +and network control, it can cause issues for developers using Docker, +particularly during build processes, where SSL certificate validation errors +might occur. This guide outlines how to configure Docker containers and builds +to properly handle Zscaler's custom certificates, ensuring smooth operation in +monitored environments. + +## The role of certificates in Docker + +When Docker builds or runs containers, it often needs to fetch resources from +the internet—whether it's pulling a base image from a registry, downloading +dependencies, or communicating with external services. In a proxied +environment, Zscaler intercepts HTTPS traffic and replaces the remote server's +certificate with its own. However, Docker doesn't trust this Zscaler +certificate by default, leading to SSL errors. + +```plaintext +x509: certificate signed by unknown authority +``` + +These errors occur because Docker cannot verify the validity of the certificate +presented by Zscaler. To avoid this, you must configure Docker to trust +Zscaler's certificate. + +## Configure Zscaler proxy for Docker Desktop + +Depending on how Zscaler is deployed, you may need to configure Docker Desktop +proxy settings manually to use the Zscaler proxy. + +If you're using Zscaler as a system-level proxy via the [Zscaler Client Connector](https://help.zscaler.com/zscaler-client-connector/what-is-zscaler-client-connector), +all traffic on the device is automatically routed through Zscaler, so Docker +Desktop uses the Zscaler proxy automatically with no additional configuration +necessary. + +If you are not using Zscaler as a system-level proxy, manually configure proxy +settings in Docker Desktop. Set up proxy settings for all clients in the +organization using [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md), +or edit proxy configuration in the Docker Desktop GUI under [**Settings > Resources > Proxies**](/manuals/desktop/settings-and-maintenance/settings.md#proxies). + +## Install root certificates in Docker images + +To enable containers to use and trust the Zscaler proxy, embed the certificate +in the image and configure the image's trust store. Installing certificates at +image build time is the preferred approach, as it removes the need for +configuration during startup and provides an auditable, consistent environment. + +### Obtaining the root certificate + +The easiest way to obtain the root certificate is to export it from a machine +where an administrator has already installed it. You can use either a web +browser or the system's certificate management service (for example, Windows +Certificate Store). + +#### Example: Exporting the certificate using Google Chrome + +1. In Google Chrome, navigate to `chrome://certificate-manager/`. +2. Under **Local certificates**, select **View imported certificates**. +3. Find the Zscaler root certificate, often labeled **Zscaler Root CA**. +4. Open the certificate details and select **Export**. +5. Save the certificate in ASCII PEM format. +6. Open the exported file in a text editor to confirm it includes `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`. + +When you have obtained the certificate, store it in an accessible repository, +such as JFrog Artifactory or a Git repository. Alternatively, use generic +storage like AWS S3. + +### Building with the certificate + +To install these certificates when building images, copy the certificate into +the build container and update the trust store. An example Dockerfile looks +like this: + +```dockerfile +FROM debian:bookworm +COPY zscaler-cert.pem /usr/local/share/ca-certificates/zscaler-cert.pem +RUN apt-get update && \ + apt-get install -y ca-certificates && \ + update-ca-certificates +``` + +Here, `zscaler-cert.pem` is the root certificate, located at the root of the +build context (often within the application's Git repository). + +If you use an artifact repository, you can fetch the certificate directly using +the `ADD` instruction. You can also use the `--checksum` flag to verify that +the content digest of the certificate is correct. + +```dockerfile +FROM debian:bookworm +ADD --checksum=sha256:24454f830cdb571e2c4ad15481119c43b3cafd48dd869a9b2945d1036d1dc68d \ + https://artifacts.example/certs/zscaler-cert.pem /usr/local/share/ca-certificates/zscaler-cert.pem +RUN apt-get update && \ + apt-get install -y ca-certificates && \ + update-ca-certificates +``` + +#### Using multi-stage builds + +For multi-stage builds where certificates are needed in the final runtime +image, ensure the certificate installation occurs in the final stage. + +```dockerfile +FROM debian:bookworm AS build +WORKDIR /build +RUN apt-get update && apt-get install -y \ + build-essential \ + cmake \ + curl \ + git +RUN --mount=target=. cmake -B output/ + +FROM debian:bookworm-slim AS final +ADD --checksum=sha256:24454f830cdb571e2c4ad15481119c43b3cafd48dd869a9b2945d1036d1dc68d \ + https://artifacts.example/certs/zscaler-cert.pem /usr/local/share/ca-certificates/zscaler-cert.pem +RUN apt-get update && \ + apt-get install -y ca-certificates && \ + update-ca-certificates +WORKDIR /app +COPY --from=build /build/output/bin . +ENTRYPOINT ["/app/bin"] +``` + +## Conclusion + +Embedding the Zscaler root certificate directly into your Docker images ensures +that containers run smoothly within Zscaler-proxied environments. By using this +approach, you reduce potential runtime errors and create a consistent, +auditable configuration that allows for smooth Docker operations within a +monitored network. diff --git a/content/manuals/copilot/_index.md b/content/manuals/copilot/_index.md new file mode 100644 index 000000000000..08f501b1113f --- /dev/null +++ b/content/manuals/copilot/_index.md @@ -0,0 +1,68 @@ +--- +title: Docker for GitHub Copilot +params: + sidebar: + badge: + color: violet + text: EA +weight: 100 +description: | + Learn how to streamline Docker-related tasks with the Docker for GitHub + Copilot extension. This integration helps you generate Docker assets, analyze + vulnerabilities, and automate containerization through GitHub Copilot Chat in + various development environments. +keywords: Docker, GitHub Copilot, extension, Visual Studio Code, chat, ai, containerization +--- + +{{% restricted title="Early Access" %}} +The Docker for GitHub Copilot extension is an [early access](/release-lifecycle#early-access-ea) product. +{{% /restricted %}} + +The [Docker for GitHub Copilot](https://github.com/marketplace/docker-for-github-copilot) +extension integrates Docker's capabilities with GitHub Copilot, providing +assistance with containerizing applications, generating Docker assets, and +analyzing project vulnerabilities. This extension helps you streamline +Docker-related tasks wherever GitHub Copilot Chat is available. + +## Key features + +Key features of the Docker for GitHub Copilot extension include: + +- Ask questions and receive responses about containerization in any context + where GitHub Copilot Chat is available, such as on GitHub.com and in Visual Studio Code. +- Automatically generate Dockerfiles, Docker Compose files, and `.dockerignore` + files for a project. +- Open pull requests with generated Docker assets directly from the chat + interface. +- Get summaries of project vulnerabilities from [Docker + Scout](/manuals/scout/_index.md) and receive next steps via the CLI. + +## Data Privacy + +The Docker agent is trained exclusively on Docker's documentation and tools to +assist with containerization and related tasks. It does not have access to your +project's data outside the context of the questions you ask. + +When using the Docker Extension for GitHub Copilot, GitHub Copilot may include +a reference to the currently open file in its request if authorized by the +user. The Docker agent can read the file to provide context-aware responses. + +If the agent is requested to check for vulnerabilities or generate +Docker-related assets, it will clone the referenced repository into in-memory +storage to perform the necessary actions. + +Source code or project metadata is never persistently stored. Questions and +answers are retained for analytics and troubleshooting. Data processed by the +Docker agent is never shared with third parties. + +## Supported languages + +The Docker Extension for GitHub Copilot supports the following programming +languages for tasks involving containerizing a project from scratch: + +- Go +- Java +- JavaScript +- Python +- Rust +- TypeScript diff --git a/content/manuals/copilot/copilot-action-prompt.png b/content/manuals/copilot/copilot-action-prompt.png deleted file mode 100644 index 0c7d7aae7a7b..000000000000 Binary files a/content/manuals/copilot/copilot-action-prompt.png and /dev/null differ diff --git a/content/manuals/copilot/examples.md b/content/manuals/copilot/examples.md new file mode 100644 index 000000000000..f9573a6a1b0f --- /dev/null +++ b/content/manuals/copilot/examples.md @@ -0,0 +1,63 @@ +--- +title: Example prompts for the Docker agent +linkTitle: Example prompts +description: | + Discover example prompts to interact with the Docker agent and learn how to + automate tasks like Dockerizing projects or opening pull requests. +weight: 30 +--- + +{{% restricted title="Early Access" %}} +The Docker for GitHub Copilot extension is an [early access](/release-lifecycle#early-access-ea) product. +{{% /restricted %}} + +## Use cases + +Here are some examples of the types of questions you can ask the Docker agent: + +### Ask general Docker questions + +You can ask general question about Docker. For example: + +- `@docker what is a Dockerfile?` +- `@docker how do I build a Docker image?` +- `@docker how do I run a Docker container?` +- `@docker what does 'docker buildx imagetools inspect' do?` + +### Get help containerizing your project + +You can ask the agent to help you containerize your existing project: + +- `@docker can you help create a compose file for this project?` +- `@docker can you create a Dockerfile for this project?` + +#### Opening pull requests + +The Docker agent will analyze your project, generate the necessary files, and, +if applicable, offer to raise a pull request with the necessary Docker assets. + +Automatically opening pull requests against your repositories is only available +when the agent generates new Docker assets. + +### Analyze a project for vulnerabilities + +The agent can help you improve your security posture with [Docker +Scout](/manuals/scout/_index.md): + +- `@docker can you help me find vulnerabilities in my project?` +- `@docker does my project contain any insecure dependencies?` + +The agent will run use Docker Scout to analyze your project's dependencies, and +report whether you're vulnerable to any [known CVEs](/manuals/scout/deep-dive/advisory-db-sources.md). + +![Copilot vulnerabilities report](images/copilot-vuln-report.png?w=500px&border=1) + +## Limitations + +- The agent is currently not able to access specific files in your repository, + such as the currently-opened file in your editor, or if you pass a file + reference with your message in the chat message. + +## Feedback + +For issues or feedback, visit the [GitHub feedback repository](https://github.com/docker/copilot-issues). diff --git a/content/manuals/copilot/copilot-button.png b/content/manuals/copilot/images/copilot-button.png similarity index 100% rename from content/manuals/copilot/copilot-button.png rename to content/manuals/copilot/images/copilot-button.png diff --git a/content/manuals/copilot/images/copilot-vuln-report.png b/content/manuals/copilot/images/copilot-vuln-report.png new file mode 100644 index 000000000000..ca203875bd03 Binary files /dev/null and b/content/manuals/copilot/images/copilot-vuln-report.png differ diff --git a/content/manuals/copilot/docker-agent-copilot.png b/content/manuals/copilot/images/docker-agent-copilot.png similarity index 100% rename from content/manuals/copilot/docker-agent-copilot.png rename to content/manuals/copilot/images/docker-agent-copilot.png diff --git a/content/manuals/copilot/index.md b/content/manuals/copilot/index.md deleted file mode 100644 index b563ffac8115..000000000000 --- a/content/manuals/copilot/index.md +++ /dev/null @@ -1,197 +0,0 @@ ---- -title: Docker for GitHub Copilot -linkTitle: Docker for GitHub Copilot -params: - sidebar: - badge: - color: violet - text: Early Access -weight: 100 -description: Learn how to use the Docker Extension for GitHub Copilot to streamline Docker-related tasks. -keywords: Docker, GitHub Copilot, extension, Visual Studio Code, chat, ai, containerization ---- - -{{% restricted title="Early access" %}} - -The Docker Extension for GitHub Copilot is a part of the [Limited Public Beta](https://github.blog/changelog/2024-05-21-copilot-extensions-now-in-limited-public-beta/) -for GitHub Copilot Extensions. - -To get access, [sign up for the Copilot Extensions waitlist](https://github.com/github-copilot/copilot_extensions_waitlist_signup). - -{{% /restricted %}} - -The Docker Extension for GitHub Copilot integrates Docker's capabilities with -GitHub Copilot, providing assistance with containerizing applications and -generating Docker assets. This extension helps you streamline Docker-related -tasks wherever GitHub Copilot Chat is available. - -The key features are: - -- Ask questions and receive responses about containerization in any context - when GitHub Copilot Chat is available, such as on GitHub.com and in Visual Studio Code. -- Automatically generate Dockerfiles, Docker Compose files, and .dockerignore - files for a project. -- Open pull requests with generated Docker assets directly from the chat - interface. -- Get summaries of project vulnerabilities from Docker Scout and receive next - steps via CLI. - -## Data Privacy - -The Docker agent is trained exclusively on Docker's documentation and tools to -assist with containerization and related tasks. It does not have access to your -project's data outside the context of the questions you ask. - -When using the Docker Extension for GitHub Copilot, GitHub Copilot may include -a reference to the currently open file in its request if authorized by the -user. The Docker agent can read the file to provide context-aware responses. - -If the agent is requested to check for vulnerabilities or generate -Docker-related assets, it will clone the referenced repository into in-memory -storage to perform the necessary actions. - -Source code, questions, and responses are not persistently stored. The Docker -agent processes data only to provide responses and discards it immediately -afterward. - -## Supported languages - -The Docker Extension for GitHub Copilot supports the following -programming languages: - -- Dockerfile -- Go -- Java -- JavaScript -- Python -- Rust -- TypeScript - -## Get Started - -Here's how to get started with the Docker Extension for GitHub Copilot. - -### Prerequisites - -Before you start, ensure that: - -- You have been granted access to GitHub's [limited public beta program](https://github.blog/changelog/2024-05-21-copilot-extensions-now-in-limited-public-beta/). -- You're signed in to your GitHub account on GitHub.com. - -### Install the extension for your organization - -1. Go to the [Docker for GitHub Copilot](https://github.com/marketplace/docker-for-github-copilot) - app in the GitHub Marketplace. - -2. Select the **Add** button at the top of the page. - -3. Under **Pricing and setup**, select the organization that you want to - install the extension for and select **Install it for free**. - -4. Select the **Complete order and begin installation** button. - -5. Select the repositories where you want to use the Docker Extension for - GitHub Copilot and finish with **Install**. - -> [!NOTE] -> Before you can use Copilot Extensions in your organization, you need to -> enable the Copilot Extensions policy. For more information, see -> [Setting a policy for GitHub Copilot Extensions in your organization](https://docs.github.com/en/copilot/managing-copilot/managing-github-copilot-in-your-organization/setting-policies-for-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization#setting-a-policy-for-github-copilot-extensions-in-your-organization). - -### Set up Copilot Chat - -Once you've installed the Docker Extension for GitHub Copilot and enabled the -Copilot Extensions policy, you can use the extension in your editor or IDE, or -on GitHub.com. - -{{< tabs >}} -{{< tab name="Editor or IDE" >}} - -For instructions on how to use the Docker Extension for GitHub Copilot in -your editor, see: - -- [Visual Studio Code](https://docs.github.com/en/copilot/github-copilot-chat/copilot-chat-in-ides/using-github-copilot-chat-in-your-ide?tool=vscode) -- [Visual Studio](https://docs.github.com/en/copilot/github-copilot-chat/copilot-chat-in-ides/using-github-copilot-chat-in-your-ide?tool=visualstudio) -- [Codespaces](https://docs.github.com/en/codespaces/reference/using-github-copilot-in-github-codespaces) - -{{< /tab >}} -{{< tab name="GitHub.com" >}} - -No setup is needed for the Docker Extension for GitHub Copilot on GitHub.com. -Simply go to any repository and start using the chat interface, -see [Using the extension](#using-the-extension). - -{{< /tab >}} -{{< /tabs >}} - -You can verify that the extension has been properly installed by typing -`@docker` in the Copilot Chat window. As you type, you should see the Docker -agent appear in the chat interface. - -![Docker agent in chat](/copilot/docker-agent-copilot.png) - -## Using the extension - -The Docker Extension for GitHub Copilot provides a chat interface that you can -use to interact with the Docker agent. You can ask questions and get help -Dockerizing your project. - -The Docker agent is trained to understand Docker-related questions, and provide -guidance on Dockerfiles, Docker Compose files, and other Docker assets. - -### Editor - -To use the extension in your editor or IDE: - -1. Open your project in your editor. -2. Open the Copilot chat interface. -3. Interact with the Docker agent using the `/docker` or `@docker`, followed by your question. - -### GitHub.com - -To use the extension in the GitHub web interface: - -1. Go to [github.com](https://github.com/) and sign in to your account. -2. Go to any repository. -3. Select the Copilot logo in the site menu to open the chat interface. - - ![Copilot chat button](/copilot/copilot-button.png?w=400px) - -4. Interact with the Docker agent by tagging `@docker`. - -## Example prompts - -Here are some examples of the types of questions you can ask the Docker agent: - -### Ask general Docker questions - -You can ask general question about Docker. For example: - -- `@docker what is a Dockerfile` -- `@docker how do I build a Docker image` -- `@docker how do I run a Docker container` - -### Ask questions about your project - -You can ask questions about your project, such as: - -- `@docker what is the best way to Dockerize this project` -- `@docker can you help me find vulnerabilities in my project?` - -The Docker agent will analyze your project, generate the necessary files, and, -if applicable, offer to raise a pull request with the necessary Docker assets. - -## Performing actions on your behalf - -Before the agent performs any actions on your behalf, such as opening a pull -request for you, you're prompted to provide your consent to allow the -operation. You can always roll back or back out of the changes. - -![Copilot action prompt](/copilot/copilot-action-prompt.png?w=400px) - -In the event that the agent encounters an error, for example during PR -creation, it handles timeouts and lack of responses gracefully. - -## Feedback - -For issues or feedback, visit the [GitHub feedback repository](https://github.com/docker/copilot-issues). diff --git a/content/manuals/copilot/install.md b/content/manuals/copilot/install.md new file mode 100644 index 000000000000..35756b6cfd2c --- /dev/null +++ b/content/manuals/copilot/install.md @@ -0,0 +1,44 @@ +--- +title: Install the extension for your organization +linkTitle: Install +description: | + Learn how to install the Docker for GitHub Copilot extension for your + organization and manage relevant policies to enable seamless integration. +weight: 10 +--- + +{{% restricted title="Early Access" %}} +The Docker for GitHub Copilot extension is an [early access](/release-lifecycle#early-access-ea) product. +{{% /restricted %}} + +To use the Docker for GitHub copilot extension, you first need to +[install](#install) the extension for your organization, and +[manage](#manage-policies) policies for Copilot in your organization. + +## Prerequisites + +Before you start, ensure that you're signed in to your GitHub account on +GitHub.com. + +## Install + +To install the Docker for GitHub Copilot extension for your GitHub organization: + +1. Go to the [Docker for GitHub Copilot](https://github.com/marketplace/docker-for-github-copilot) + app in the GitHub Marketplace. + +2. Select the **Add** button at the top of the page. + +3. Under **Pricing and setup**, select the organization that you want to + install the extension for and select **Install it for free**. + +4. Select the **Complete order and begin installation** button. + +5. Select the repositories where you want to use the Docker Extension for + GitHub Copilot and finish with **Install**. + +## Manage policies + +If you're enabling the extension for a GitHub organization, you also +need to enable the Copilot Extensions policy. For instructions, see +[Setting a policy for GitHub Copilot Extensions in your organization](https://docs.github.com/en/copilot/managing-copilot/managing-github-copilot-in-your-organization/setting-policies-for-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization#setting-a-policy-for-github-copilot-extensions-in-your-organization). diff --git a/content/manuals/copilot/usage.md b/content/manuals/copilot/usage.md new file mode 100644 index 000000000000..92cba9c494a6 --- /dev/null +++ b/content/manuals/copilot/usage.md @@ -0,0 +1,65 @@ +--- +title: Using the Docker for GitHub Copilot extension +linkTitle: Usage +description: | + Learn how to use the Docker for GitHub Copilot extension to interact with the + Docker agent, get help Dockerizing projects, and ask Docker-related questions + directly from your IDE or GitHub.com. +weight: 20 +--- + +{{% restricted title="Early Access" %}} +The Docker for GitHub Copilot extension is an [early access](/release-lifecycle#early-access-ea) product. +{{% /restricted %}} + +The Docker Extension for GitHub Copilot provides a chat interface that you can +use to interact with the Docker agent. You can ask questions and get help +Dockerizing your project. + +The Docker agent is trained to understand Docker-related questions, and provide +guidance on Dockerfiles, Docker Compose files, and other Docker assets. + +## Setup + +Before you can start interacting with the Docker agent, make sure you've +[installed](./install.md) the extension for your organization. + +### Enable GitHub Copilot chat in your editor or IDE + +For instructions on how to use the Docker Extension for GitHub Copilot in +your editor, see: + +- [Visual Studio Code](https://docs.github.com/en/copilot/github-copilot-chat/copilot-chat-in-ides/using-github-copilot-chat-in-your-ide?tool=vscode) +- [Visual Studio](https://docs.github.com/en/copilot/github-copilot-chat/copilot-chat-in-ides/using-github-copilot-chat-in-your-ide?tool=visualstudio) +- [Codespaces](https://docs.github.com/en/codespaces/reference/using-github-copilot-in-github-codespaces) + +### Verify the setup + +You can verify that the extension has been properly installed by typing +`@docker` in the Copilot Chat window. As you type, you should see the Docker +agent appear in the chat interface. + +![Docker agent in chat](images/docker-agent-copilot.png) + +The first time you interact with the agent, you're prompted to sign in and +authorize the Copilot extension with your Docker account. + +## Asking Docker questions in your editor + +To interact with the Docker agent from within your editor or IDE: + +1. Open your project in your editor. +2. Open the Copilot chat interface. +3. Interact with the Docker agent by tagging `@docker`, followed by your question. + +## Asking Docker questions on GitHub.com + +To interact with the Docker agent from the GitHub web interface: + +1. Go to [github.com](https://github.com/) and sign in to your account. +2. Go to any repository. +3. Select the Copilot logo in the site menu, or select the floating Copilot widget, to open the chat interface. + + ![Copilot chat button](images/copilot-button.png?w=400px) + +4. Interact with the Docker agent by tagging `@docker`, followed by your question. diff --git a/hugo_stats.json b/hugo_stats.json index fb4024a5d39d..9e492820c9b4 100644 --- a/hugo_stats.json +++ b/hugo_stats.json @@ -43,7 +43,6 @@ "Docker-Hub", "Docker-Scout-Dashboard", "Download", - "Editor-or-IDE", "Entra-ID", "Entra-ID-SAML-2.0", "External-cloud-storage", @@ -57,7 +56,6 @@ "Git-Bash", "Git-Bash-CLI", "GitHub-Actions", - "GitHub.com", "GitLab", "Go", "HTTP",