Merge pull request #21363 from docker/published-update

publish updates from main

Author: dvdksn

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

_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?

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.

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

content/manuals/copilot/copilot-action-prompt.png

@@ -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).