diff --git a/.github/labeler.yml b/.github/labeler.yml index 719a3ab98f04..bd7e0104000c 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -59,6 +59,7 @@ area/engine: - changed-files: - any-glob-to-any-file: - content/manuals/engine/** + - content/reference/api/engine/** area/install: - changed-files: diff --git a/Dockerfile b/Dockerfile index f5432d03461a..c551c27038d9 100644 --- a/Dockerfile +++ b/Dockerfile @@ -7,42 +7,27 @@ ARG ALPINE_VERSION=3.20 ARG GO_VERSION=1.23 # HTMLTEST_VERSION sets the wjdp/htmltest version for HTML testing ARG HTMLTEST_VERSION=0.17.0 +# HUGO_VERSION sets the version of Hugo to build the site with +ARG HUGO_VERSION=0.136.0 -# base is the base stage with build dependencies -FROM golang:${GO_VERSION}-alpine AS base -WORKDIR /src -RUN apk --update add nodejs npm git gcompat - -# node installs Node.js dependencies -FROM base AS node -COPY package*.json . -ENV NODE_ENV=production -RUN npm install - -# hugo downloads and extracts the Hugo binary -FROM base AS hugo -ARG HUGO_VERSION=0.134.3 -ARG TARGETARCH -WORKDIR /tmp/hugo -RUN wget -O "hugo.tar.gz" "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-${TARGETARCH}.tar.gz" -RUN tar -xf "hugo.tar.gz" hugo - -# build-base is the base stage for building the site -FROM base AS build-base -COPY --from=hugo /tmp/hugo/hugo /bin/hugo -COPY --from=node /src/node_modules /src/node_modules +# build-base is the base stage used for building the site +FROM ghcr.io/gohugoio/hugo:v${HUGO_VERSION} AS build-base +USER root +ENV NODE_ENV="production" +RUN --mount=source=package.json,target=package.json \ + --mount=source=package-lock.json,target=package-lock.json \ + --mount=type=cache,target=/root/.npm \ + npm ci COPY . . -# dev is for local development with Docker Compose -FROM build-base AS dev - # build creates production builds with Hugo FROM build-base AS build # HUGO_ENV sets the hugo.Environment (production, development, preview) -ARG HUGO_ENV +ARG HUGO_ENV="development" # DOCS_URL sets the base URL for the site -ARG DOCS_URL -RUN hugo --gc --minify -d /out -e $HUGO_ENV -b $DOCS_URL +ARG DOCS_URL="https://docs.docker.com" +RUN --mount=type=cache,target=/cache \ + hugo --gc --minify -d /out -e $HUGO_ENV -b $DOCS_URL # lint lints markdown files FROM davidanson/markdownlint-cli2:v0.14.0 AS lint @@ -122,7 +107,7 @@ fi EOT # pagefind installs the Pagefind runtime -FROM base AS pagefind +FROM node:alpine${ALPINE_VERSION} AS pagefind ARG PAGEFIND_VERSION=1.1.1 COPY --from=build /out ./public RUN --mount=type=bind,src=pagefind.yml,target=pagefind.yml \ diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt index 35a06b4664e0..b26aee03523a 100644 --- a/_vale/config/vocabularies/Docker/accept.txt +++ b/_vale/config/vocabularies/Docker/accept.txt @@ -65,12 +65,16 @@ Grafana Gravatar HTTP HyperKit +IAM IPs? IPv[46] IPvlan Intel +Intune +Jamf JFrog JetBrains +Kerberos Kitematic Kubernetes LTS @@ -80,16 +84,20 @@ Logstash MAC Mac Mail(chimp|gun) +MDM Microsoft MySQL NAT Netplan Nginx +NTLM Nuxeo +OAT OAuth OCI OTel Okta +PAT Postgres PowerShell Python @@ -138,8 +146,10 @@ Zsh [Ff]iletypes? [GgCc]oroutine [Hh]ostname +[Ii]nfosec [Ll]oopback [Mm]oby +[Oo]nboarding [Pp]aravirtualization [Pp]roxying [Rr]eal-time @@ -149,10 +159,12 @@ Zsh [Ss]warm [Tt]oolchains? [Vv]irtualize +[Vv]irtiofs [Ww]alkthrough cgroup config containerd +deprovisioning deserialization deserialize displayName @@ -187,4 +199,4 @@ ufw umask ungated vSphere -virtiofs +vpnkit diff --git a/archetypes/guides.md b/archetypes/guides.md new file mode 100644 index 000000000000..e92dea738922 --- /dev/null +++ b/archetypes/guides.md @@ -0,0 +1,13 @@ +--- +title: '{{ replace .File.ContentBaseName `-` ` ` | humanize }}' +# linkTitle: A shorter, alternative title +description: # Meta description for SEO. +summary: | # A summary of what's in this guide + In this guide, ... +languages: [] # Programming languages used +products: [] # Docker products involved +levels: [] # Experience level(s) of the intended audience (beginner|intermediate|advanced) +subjects: [] # What's it about? +params: + # time: 10 minutes +--- diff --git a/assets/images/guides/bake.webp b/assets/images/guides/bake.webp new file mode 100644 index 000000000000..7080871bd84d Binary files /dev/null and b/assets/images/guides/bake.webp differ diff --git a/assets/images/learning-paths/container-supported-development.png b/assets/images/learning-paths/container-supported-development.png new file mode 100644 index 000000000000..a9e09665bbee Binary files /dev/null and b/assets/images/learning-paths/container-supported-development.png differ diff --git a/compose.yaml b/compose.yaml index c8b7dc5f823b..27b072077494 100644 --- a/compose.yaml +++ b/compose.yaml @@ -2,7 +2,7 @@ services: server: build: context: . - target: dev + target: build-base ports: - "1313:1313" entrypoint: ["hugo", "server", "--bind", "0.0.0.0"] @@ -11,5 +11,3 @@ services: - action: sync path: . target: /src - ignore: - - node_modules/ \ No newline at end of file diff --git a/content/contribute/guides.md b/content/contribute/guides.md new file mode 100644 index 000000000000..ac775387465a --- /dev/null +++ b/content/contribute/guides.md @@ -0,0 +1,260 @@ +--- +title: Guidelines for writing Docker usage guides +linkTitle: Write a Docker guide +description: Learn how to write guides for learning about Docker, with Docker. +--- + + + +This guide provides instructions and best practices for writing tutorial-style +usage guides that help users achieve specific goals using Docker. These guides +will be featured in the [guides section](/guides/_index.md) of the website, +alongside our product manuals and reference materials. + +Our documentation is written in Markdown, with YAML front matter for metadata. +We use [Hugo](https://gohugo.io) to build the website. For more information +about how to write content for Docker docs, refer to our +[CONTRIBUTING.md](https://github.com/docker/docs/tree/main/CONTRIBUTING.md). + +## Purpose of the guides + +Our usage guides aim to: + +- Educate users on how to leverage Docker in various contexts. +- Provide practical, hands-on experience through step-by-step tutorials. +- Help users achieve specific goals relevant to their interests or projects. + +## Audience + +- Experience levels: From beginners to advanced users. +- Roles: Developers, system administrators, DevOps engineers, and more. +- Technologies: Various programming languages and frameworks. + +## Metadata for guides + +Each guide must include a metadata section at the beginning of the document. +This metadata helps users discover and filter guides based on their interests +and needs. + +### Example metadata format + +```yaml +--- +title: Deploy a machine learning model with Docker +linkTitle: Docker for ML deployment +description: Learn how to containerize and deploy a machine learning model using Docker. +summary: | + This guide walks you through the steps to containerize a machine learning + model and deploy it using Docker, enabling scalable and portable AI + solutions. +languages: [python] +subjects: [machine-learning, deployment] +levels: [intermediate] +params: + time: 30 minutes +--- +``` + +### Metadata fields + +- `title` (required): The main title of the guide in sentence case. +- `linkTitle` (optional): A shorter title used in navigation menus. +- `description` (required): A concise description for SEO purposes. +- `summary` (required): A brief overview of the guide's content. +- `languages` (optional): List of programming languages used. +- `subjects` (optional): Domains or subject areas covered. +- `levels` (optional): Intended audience experience level (`beginner`, `intermediate`, `advanced`). +- `products` (optional): List of programming languages used. +- `params` + - `time` (optional): Estimated reading or completion time. + +The `languages`, `subjects`, `levels`, and `products` keys are taxonomies, and +the values are used to associate the page with the filter options on the guides +landing page. + +## Document structure + +Our guides emphasize learning by doing. Depending on the type of guide, the +structure may vary to best suit the content and provide a smooth learning +experience. + +All guides live directly under the `content/guides/` directory in the Docker +docs repository. Guides can either be a single page or multiple pages. In the +case of multi-page guides, every page is a step in a sequential workflow. + +If you're creating a single-page guide, create a single markdown file in the +guides directory: + +```bash +# Create the file +touch content/guides/my-docker-guide.md +# or if you have Hugo installed: +hugo new content/guides/my-docker-guide.md +``` + +To create a multi-page guide, create a directory where each page is a markdown +file, with an `_index.md` file representing the introduction to the guide. + +```bash +# Create the index page for the guide +mkdir content/guides/my-docker-guide.md +touch content/guides/my-docker-guide/_index.md +# or if you have Hugo installed: +hugo new content/guides/my-docker-guide/_index.md +``` + +Then create the pages for the guide under `content/guides//.md` as +needed. The [metadata](#metadata-for-guides) lives on the `_index.md` page (you +don't need to assign metadata to individual pages). + +### Guides for specific frameworks or languages + +For guides that demonstrate how to use Docker with a particular framework or +programming language, consider the following outline: + +1. **Introduction** + - Briefly introduce the framework or language in the context of Docker. + - Explain what the user will achieve by the end of the guide. + - List required software, tools, and knowledge. +2. **Development setup** + - Guide the user through setting up a development environment. + - Include instructions on writing or obtaining sample code. + - Show how to run containers for local development. +3. **Building the application** + - Explain how to create a Dockerfile tailored to the application. + - Provide step-by-step instructions for building the Docker image. + - If applicable, show how to test the application using Docker. +4. **Deploying with Docker** + - Show how to run the application in a Docker container. + - Discuss configuration options and best practices. +5. **Best practices and conclusions** + - Offer tips for optimizing Docker usage with the framework or language. + - Summarize key takeaways, suggest next steps, and further reading. + +### Use-case guides + +For guides focused on accomplishing a specific goal or use case with Docker +(e.g., deploying a machine learning model), use a flexible outline that ensures +a logical flow. + +The following outline is an example. The structure should be adjusted to best +fit the content and ensure a clear, logical progression. Depending on the +subject matter of your use-case guide, the exact structure will vary. + +1. **Introduction** + - Describe the problem or goal. + - Explain the benefits of using Docker in this context. +2. **Prerequisites** + - List required tools, technologies, and prior knowledge. +3. **Setup** + - Provide instructions for setting up the environment. + - Include any necessary configuration steps. +4. **Implementation** + - Walk through the process step by step. + - Use code snippets and explanations to illustrate key points. +5. **Running or deploying the application** + - Guide the user on how to execute or deploy the solution. + - Discuss any verification steps to ensure success. +6. **Conclusion** + - Recap what was achieved. + - Suggest further reading or advanced topics. + +## Example code + +If you create an example repository with source code to accompany your guide, +we strongly encourage you to publish that repository under the +[dockersamples](https://github.com/dockersamples) organization on GitHub. +Publishing your source code under this organization, rather than your personal +account, ensures that the source code remains accessible to the maintainers of +the documentation site after publishing. In the event of a bug or an issue in +the guide, the documentation team can more easily update the guide and its +corresponding example repository. + +Hosting the examples in the official samples namespace also helps secure trust +with users who are reading the guide. + +### Publish a repository under `dockersamples` + +To publish your repository under the `dockersamples` organization, use the +[dockersamples template](https://github.com/dockersamples/sample-app-template) +to initiate a sample repository under your personal namespace. When you've +finished drafting your content and opened your pull request for the +documentation, we can transfer the repository to the dockersamples +organization. + +## Writing style + +Use [sentence case](/contribute/style/formatting.md#capitalization) for all +headings and titles. This means only the first word and proper nouns are +capitalized. + +### Voice and tone + +- **Clarity and conciseness**: Use simple language and short sentences to convey information effectively. +- **Active voice**: Write in the active voice to engage the reader (e.g., "Run the command" instead of "The command should be run"). +- **Consistency**: Maintain a consistent tone and terminology throughout the guide. + +For detailed guidelines, refer to our [voice and tone documentation](/contribute/style/voice-tone.md). + +### Formatting conventions + +- **Headings**: Use H2 for main sections and H3 for subsections, following sentence case. +- **Code examples**: Provide complete, working code snippets with syntax highlighting. +- **Lists and steps**: Use numbered lists for sequential steps and bullet points for non-sequential information. +- **Emphasis**: Use bold for UI elements (e.g., **Button**), and italics for emphasis. +- **Links**: Use descriptive link text (e.g., [Install Docker](/get-started/get-docker.md)). + +For more details, see our [content formatting guidelines](/contribute/style/formatting.md) +and [grammar and style rules](/contribute/style/grammar.md). + +## Best practices + +- **Test all instructions** + - Ensure all code and commands work as expected. + - Verify that the guide can be followed successfully from start to finish. +- **Relevance** + - Focus on real-world applications and scenarios. + - Keep the content up-to-date with the latest Docker versions. +- **Troubleshooting tips** + - Anticipate common issues and provide solutions or references. +- **Visual aids** + - Include screenshots or diagrams where they enhance understanding. + - Add captions and alt text for accessibility. +- **Third-party tools** + - Avoid requiring the user to install third-party tools or modify their local development environment. + - Prefer using containerized tools and methods where applicable (e.g. `docker exec`). + - Some tools are reasonable to assume as installed or prerequisites for guides, such as Node.js and npm. Use your better judgement. + +## Additional resources + +- **Existing guides** + - Refer to [Docker Guides](/guides/_index.md) for examples and inspiration. +- **Style guides** + - [Voice and tone](/contribute/style/voice-tone.md) + - [Content formatting](/contribute/style/formatting.md) + - [Grammar and style](/contribute/style/grammar.md) + +## Submission process + +- **Proposal** + - Raise an issue on the [Docker documentation GitHub repository](https://github.com/docker/docs) + with a request to add a new guide. + - Once the proposal has been accepted, start writing your guide by forking + the repository and creating a branch for your work. + + > [!NOTE] + > Avoid contributing from the `main` branch of your fork, since it makes it + > more difficult for maintainers to help you fix any issues that may arise. + +- **Review** + - Proofread your guide for grammar, clarity, and adherence to the guidelines. + - Once your draft is ready, raise a pull request, with a reference to the + original issue. + - The Docker documentation team and subject matter experts will review your + submission and provide feedback on the pull request directly. +- **Publishing** + - Your guide will be published on the Docker documentation website when the + reviewers have approved and merged your pull request. + +Thank you for contributing to the Docker community. Your expertise helps users +worldwide harness the power of Docker. diff --git a/content/get-started/workshop/06_bind_mounts.md b/content/get-started/workshop/06_bind_mounts.md index 9f2a20098774..8a825759c73c 100644 --- a/content/get-started/workshop/06_bind_mounts.md +++ b/content/get-started/workshop/06_bind_mounts.md @@ -59,7 +59,7 @@ filesystem you can share with containers. For details about accessing the settin bind mount. {{< tabs >}} - {{< tab name="Mac / Linux / PowerShell" >}} + {{< tab name="Mac / Linux" >}} ```console $ docker run -it --mount type=bind,src="$(pwd)",target=/src ubuntu bash @@ -79,6 +79,13 @@ filesystem you can share with containers. For details about accessing the settin $ docker run -it --mount type=bind,src="/$(pwd)",target=/src ubuntu bash ``` + {{< /tab >}} + {{< tab name="PowerShell" >}} + + ```console + $ docker run -it --mount "type=bind,src=$($pwd),target=/src" ubuntu bash + ``` + {{< /tab >}} {{< /tabs >}} diff --git a/content/guides/admin-set-up/_index.md b/content/guides/admin-set-up/_index.md new file mode 100644 index 000000000000..0a5bff1818fc --- /dev/null +++ b/content/guides/admin-set-up/_index.md @@ -0,0 +1,69 @@ +--- +title: Set up your company for success with Docker +linkTitle: Admin set up +summary: Get the most out of Docker by streamlining workflows, standardizing development environments, and ensuring smooth deployments across your company. +description: Learn how to onboard your company and take advantage of all of the Docker products and features. +levels: [intermediate] +params: + featured: true + image: + resource_links: + - title: Overview of Administration in Docker + url: /admin/ + - title: Single sign-on + url: /security/for-admins/single-sign-on/ + - title: Enforce sign-in + url: /security/for-admins/enforce-sign-in/ + - title: Roles and permissions + url: /security/for-admins/roles-and-permissions/ + - title: Settings Management + url: /security/for-admins/hardened-desktop/settings-management/ + - title: Registry Access Management + url: /security/for-admins/hardened-desktop/registry-access-management/ + - title: Image Access Management + url: /security/for-admins/hardened-desktop/image-access-management/ + - title: Docker Build Cloud subscription information + url: /subscription/build-cloud/build-details/ + - title: Docker Scout subscription information + url: /subscription/scout-details/ +--- + +Docker's tools provide a scalable, secure platform that empowers your developers to create, ship, and run applications faster. As an administrator, you have the ability to streamline workflows, standardize development environments, and ensure smooth deployments across your organization. + +By configuring Docker products to suit your company’s needs, you can optimize performance, simplify user management, and maintain control over resources. This guide will help you set up and configure Docker products to maximize productivity and success for your team whilst meeting compliance and security policies + +## Who’s this for? + +- Administrators responsible for managing Docker environments within their organization +- IT leaders looking to streamline development and deployment workflows +- Teams aiming to standardize application environments across multiple users +- Organizations seeking to optimize their use of Docker products for greater scalability and efficiency +- Organizations with [Docker Business subscriptions](https://www.docker.com/pricing/). + +## What you’ll learn + +- The importance of signing in to the company's Docker organization for access to usage data and enhanced functionality. +- How to standardize Docker Desktop versions and settings to create a consistent baseline for all users, while allowing flexibility for advanced developers. +- Strategies for implementing Docker’s security configurations to meet company IT and software development security requirements without hindering developer productivity. + +## Features covered + +- Organizations. These are the core structure for managing your Docker environment, grouping users, teams, and image repositories. Your organization was created with your subscription and is managed by one or more Owners. Users signed into the organization are assigned seats based on the purchased subscription. +- Enforce sign-in. By default, Docker Desktop does not require sign-in. However, you can configure settings to enforce this and ensure your developers sign in to your Docker organization. +- SSO. Without SSO, user management in a Docker organization is manual. Setting up an SSO connection between your identity provider and Docker ensures compliance with your security policy and automates user provisioning. Adding SCIM further automates user provisioning and de-provisioning. +- General and security settings. Configuring key settings will ensure smooth onboarding and usage of Docker products within your environment. Additionally, you can enable security features based on your company's specific security needs. + +## Who needs to be involved? + +- Docker organization owner: A Docker organization owner must be involved in the process and will be required for several key steps. +- DNS team: The DNS team is needed during the SSO setup to verify the company domain. +- MDM team: Responsible for distributing Docker-specific configuration files to developer machines. +- Identity Provider team: Required for configuring the identity provider and establishing the SSO connection during setup. +- Development lead: A development lead with knowledge of Docker configurations to help establish a baseline for developer settings. +- IT team: An IT representative familiar with company desktop policies to assist with aligning Docker configuration to those policies. +- Infosec: A security team member with knowledge of company development security policies to help configure security features. +- Docker testers: A small group of developers to test the new settings and configurations before full deployment. + +## Tools integration + +Okta, Entra ID SAML 2.0, Azure Connect (OIDC), MDM solutions like Intune \ No newline at end of file diff --git a/content/guides/admin-set-up/comms-and-info-gathering.md b/content/guides/admin-set-up/comms-and-info-gathering.md new file mode 100644 index 000000000000..a70f525ab160 --- /dev/null +++ b/content/guides/admin-set-up/comms-and-info-gathering.md @@ -0,0 +1,33 @@ +--- +title: Communication and information gathering +description: Gather your company's requirements from key stakeholders and communicate to your developers. +weight: 10 +--- + +## Step one: Communicate with your developers and IT teams + +### Docker user communication + +You may already have Docker Desktop users within your company, and some steps in this process may affect how they interact with the platform. It's highly recommended to communicate early with users, informing them that as part of the subscription onboarding, they will be upgraded to a supported version of Docker Desktop. + +Additionally, communicate that settings will be reviewed to optimize productivity, and users will be required to sign in to the company’s Docker organization using their business email to fully utilize the subscription benefits. + +### MDM team communication + +Device management solutions, such as Intune and Jamf, are commonly used for software distribution across enterprises, typically managed by a dedicated MDM team. It is recommended that you engage with this team early in the process to understand their requirements and the lead time for deploying changes. + +Several key setup steps in this guide require the use of JSON files, registry keys, or .plist files that need to be distributed to developer machines. It’s a best practice to use MDM tools for deploying these configuration files and ensuring their integrity is preserved. + +## Step two: Identify Docker organizations + +Some companies may have more than one [Docker organization](/manuals/admin/organization/_index.md) created. These organizations may have been created for specific purposes, or may not be needed anymore. If you suspect your company has more than one Docker organization, it's recommended you survey your teams to see if they have their own organizations. You can also contact your Docker Customer Success representative to get a list of organizations with users whose emails match your domain name. + +## Step three: Gather requirements + +Through [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md), Docker provides numerous configuration parameters that can be preset. The Docker organization owner, development lead, and infosec representative should review these settings to establish the company’s baseline configuration, including security features and [enforcing sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) for Docker Desktop users. Additionally, they should decide whether to take advantage of free trials for other Docker products, such as [Docker Scout](/manuals/scout/_index.md), which is included in the subscription. + +To view the parameters that can be preset, see [Configure Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/configure.md#step-two-configure-the-settings-you-want-to-lock-in). + +## Optional step four: Meet with the Docker Implementation team + +The Docker Implementation team can help you step through setting up your organization, configuring SSO, enforcing sign in, and configuring Docker. You can reach out to set up a meeting by emailing successteam@docker.com. diff --git a/content/guides/admin-set-up/deploy.md b/content/guides/admin-set-up/deploy.md new file mode 100644 index 000000000000..ab91d9f4e568 --- /dev/null +++ b/content/guides/admin-set-up/deploy.md @@ -0,0 +1,18 @@ +--- +title: Deploy +description: Deploy your Docker setup across your company. +weight: 40 +--- + +> [!WARNING] +> Ensure you communicate with your users before proceeding, and confirm that your IT and MDM teams are prepared to handle any unexpected issues, as these steps will affect all existing users signing into your Docker organization. + +## Step one: Enforce SSO + +Enforcing SSO means that anyone who has a Docker profile with an email address that matches your verified domain must sign in using your SSO connection. Make sure the Identity provider groups associated with your SSO connection cover all the developer groups that you want to have access to the Docker subscription. + +## Step two: Deploy configuration settings and enforce sign-in to users + +Have the MDM team deploy the configuration files for Docker to all users. + +Congratulations, you have successfully completed the admin implementation process for Docker. diff --git a/content/guides/admin-set-up/finalize-plans-and-setup.md b/content/guides/admin-set-up/finalize-plans-and-setup.md new file mode 100644 index 000000000000..3f085fb1c556 --- /dev/null +++ b/content/guides/admin-set-up/finalize-plans-and-setup.md @@ -0,0 +1,43 @@ +--- +title: Finalize plans and begin setup +description: Collaborate with your MDM team to distribute configurations and set up SSO and Docker product trials. +weight: 20 +--- + +## Step one: Send finalized settings files to the MDM team + +After reaching an agreement with the relevant teams on your baseline and security configurations as outlined in module one, follow the instructions in the [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md) documentation to create the `admin-settings.json` file that captures these configurations. + +Once the file is ready, collaborate with your MDM team to deploy the `admin-settings.json` file, along with your chosen method for [enforcing sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md). + +> [!IMPORTANT] +> +> It’s highly recommended that you test this first with a small number of Docker Desktop developers to verify the functionality works as expected before deploying more widely. + +## Step two: Manage your organizations + +If you have more than one organization, it’s recommended that you either consolidate them into one organization or create a [Docker company](/manuals/admin/company/_index.md) to manage multiple organizations. Work with the Docker Customer Success and Implementation teams to make this happen. + +## Step three: Begin setup + +### Set up single sign-on SSO domain verification + +Single sign-on (SSO) lets developers authenticate using their identity providers (IdPs) to access Docker. SSO is available for a whole company, and all associated organizations, or an individual organization that has a Docker Business subscription. For more information, see the [documentation](/manuals/security/for-admins/single-sign-on/_index.md). + +You can also enable [SCIM](/manuals/security/for-admins/provisioning/scim.md) for further automation of provisioning and deprovisioning of users. + +### Set up free tier Docker product entitlements included in the subscription + +[Docker Build Cloud](/manuals/build-cloud/_index.md) significantly reduces build times, both locally and in CI, by providing a dedicated remote builder and shared cache. Powered by the cloud, developer time and local resources are freed up so your team can focus on more important things, like innovation. To get started, [set up a cloud builder](http://build.docker.com). + +[Docker Scout](manuals/scout/_index.md) is a solution for proactively enhancing your software supply chain security. By analyzing your images, Docker Scout compiles an inventory of components, also known as a Software Bill of Materials (SBOM). The SBOM is matched against a continuously updated vulnerability database to pinpoint security weaknesses. To get started, see [Quickstart](/manuals/scout/quickstart.md). + +### Ensure you're running a supported version of Docker Desktop + +> [!WARNING] +> +> This step could affect the experience for users on older versions of Docker Desktop. + +Existing users may be running outdated or unsupported versions of Docker Desktop. It is highly recommended that all users update to a supported version. Docker Desktop versions released within the past 6 months from the latest release are supported. + +It's recommended that you use a MDM solution to manage the version of Docker Desktop for users. Users may also get Docker Desktop directly from Docker or through a company software portal. diff --git a/content/guides/admin-set-up/testing.md b/content/guides/admin-set-up/testing.md new file mode 100644 index 000000000000..d4fd0b805ccc --- /dev/null +++ b/content/guides/admin-set-up/testing.md @@ -0,0 +1,32 @@ +--- +title: Testing +description: Test your Docker setup. +weight: 30 +--- + +## SSO and SCIM testing + +You can test SSO and SCIM by signing in to Docker Desktop or Docker Hub with the email address linked to a Docker account that is part of the verified domain. Developers who sign in using their Docker usernames will remain unaffected by the SSO and/or SCIM setup. + +> [!IMPORTANT] +> +> Some users may need CLI based logins to Docker Hub, and for this they will need a [personal access token (PAT)](/manuals/security/for-developers/access-tokens.md). + +## Test RAM and IAM + +> [!WARNING] +> Be sure to communicate with your users before proceeding, as this step will impact all existing users signing into your Docker organization + +If you plan to use [Registry Access Management (RAM)](/manuals/security/for-admins/hardened-desktop/registry-access-management.md) and/or [Image Access Management (IAM)](/manuals/security/for-admins/hardened-desktop/image-access-management.md), ensure your test developer signs in to Docker Desktop using their organization credentials. Once authenticated, have them attempt to pull an unauthorized image or one from a disallowed registry via the Docker CLI. They should receive an error message indicating that the registry is restricted by the organization. + +## Deploy settings and enforce sign in to test group + +Deploy the Docker settings and enforce sign-in for a small group of test users via MDM. Have this group test their development workflows with containers on Docker Desktop and Docker Hub to ensure all settings and the sign-in enforcement function as expected. + +## Test Build Cloud capabilities + +Have one of your Docker Desktop testers [connect to the cloud builder you created and use it to build](/manuals/build-cloud/usage.md). + +## Verify Scout monitoring of repositories + +Check the [Docker Scout dashboard](https://scout.docker.com/) to confirm that data is being properly received for the repositories where Docker Scout has been enabled. diff --git a/content/guides/bake/index.md b/content/guides/bake/index.md new file mode 100644 index 000000000000..c3eafa98d12c --- /dev/null +++ b/content/guides/bake/index.md @@ -0,0 +1,518 @@ +--- +title: Mastering multi-platform builds, testing, and more with Docker Buildx Bake +linkTitle: Mastering Docker Buildx Bake +description: > + Learn how to manage simple and complex build configurations with Buildx Bake. +summary: > + Learn to automate Docker builds and testing with declarative configurations using Buildx Bake. +languages: [go] +subjects: [devops] +levels: [advanced] +params: + time: 30 minutes + featured: true + image: /images/guides/bake.webp +--- + +This guide demonstrates how to simplify and automate the process of building +images, testing, and generating build artifacts using Docker Buildx Bake. By +defining build configurations in a declarative `docker-bake.hcl` file, you can +eliminate manual scripts and enable efficient workflows for complex builds, +testing, and artifact generation. + +## Assumptions + +This guide assumes that you're familiar with: + +- Docker +- [Buildx](/manuals/build/concepts/overview.md#buildx) +- [BuildKit](/manuals/build/concepts/overview.md#buildkit) +- [Multi-stage builds](/manuals/build/building/multi-stage.md) +- [Multi-platform builds](/manuals/build/building/multi-platform.md) + +## Prerequisites + +- A recent version of Docker is installed on your machine. +- Git is installed for cloning repositories. +- You're using the [containerd](/manuals/desktop/containerd.md) image store. + +## Introduction + +This guide uses an example project to demonstrate how Docker Buildx Bake can +streamline your build and test workflows. This repository includes both a +Dockerfile and `docker-bake.hcl`, giving you a ready-to-use setup to try out +Bake commands. + +Start by cloning the example repository: + +```bash +git clone https://github.com/dvdksn/bakeme.git +cd bakeme +``` + +The Bake file, `docker-bake.hcl`, defines the build targets in a declarative +syntax, using targets and groups, allowing you to manage complex builds +efficiently. + +Here's what the Bake file looks like out-of-the-box: + +```hcl +target "default" { + target = "image" + tags = [ + "bakeme:latest", + ] + attest = [ + "type=provenance,mode=max", + "type=sbom", + ] + platforms = [ + "linux/amd64", + "linux/arm64", + "linux/riscv64", + ] +} +``` + +The `target` keyword defines a build target for Bake. The `default` target +defines the target to build when no specific target is specified on the command +line. Here's a quick summary of the options for the `default` target: + +- `target`: The target build stage in the Dockerfile. +- `tags`: Tags to assign to the image. +- `attest`: [Attestations](/manuals/build/metadata/attestations/_index.md) to attach to the image. + + > [!TIP] + > The attestations provide metadata such as build provenance, which tracks + > the source of the image's build, and an SBOM (Software Bill of Materials), + > useful for security audits and compliance. + +- `platforms`: Platform variants to build. + +To execute this build, simply run the following command in the root of the +repository: + +```console +$ docker buildx bake +``` + +With Bake, you avoid long, hard-to-remember command-line incantations, +simplifying build configuration management by replacing manual, error-prone +scripts with a structured configuration file. + +For contrast, here's what this build command would look like without Bake: + +```console +$ docker buildx build \ + --target=image \ + --tag=bakeme:latest \ + --provenance=true \ + --sbom=true \ + --platform=linux/amd64,linux/arm64,linux/riscv64 \ + . +``` + +## Testing and linting + +Bake isn't just for defining build configurations, and running builds. You can +also use Bake to run your tests, effectively using BuildKit as a task runner. +Running your tests in containers is great for ensuring reproducible results. +This section shows how to add two types of tests: + +- Unit testing with `go test`. +- Linting for style violations with `golangci-lint`. + +In Test-Driven Development (TDD) fashion, start by adding a new `test` target +to the Bake file: + +```hcl +target "test" { + target = "test" + output = ["type=cacheonly"] +} +``` + +> [!TIP] +> Using the `type=cacheonly` ensures that the build output is effectively +> discarded; the layers are saved to BuildKit's cache, but Buildx will not +> attempt to load the result to the Docker Engine's image store. +> +> For test runs, you don't need to export the build output — only the test +> execution matters. + +To execute this Bake target, run `docker buildx bake test`. At this time, +you'll receive an error indicating that the `test` stage does not exist in the +Dockerfile. + +```console +$ docker buildx bake bake test +[+] Building 1.2s (6/6) FINISHED + => [internal] load local bake definitions +... +ERROR: failed to solve: target stage "test" could not be found +``` + +To satisfy this target, add the corresponding Dockerfile target. The `test` +stage here is based on the same base stage as the build stage. + +```dockerfile +FROM base AS test +RUN --mount=target=. \ + --mount=type=cache,target=/go/pkg/mod \ + go test . +``` + +> [!TIP] +> The [`--mount=type=cache` directive](/manuals/build/cache/optimize.md#use-cache-mounts) +> caches Go modules between builds, improving build performance by avoiding the +> need to re-download dependencies. This shared cache ensures that the same +> dependency set is available across build, test, and other stages. + +Now, running the `test` target with Bake will evaluate the unit tests for this +project. If you want to verify that it works, you can make an arbitrary change +to `main_test.go` to cause the test to fail. + +Next, to enable linting, add another target to the Bake file, named `lint`: + +```hcl +target "lint" { + target = "lint" + output = ["type=cacheonly"] +} +``` + +And in the Dockerfile, add the build stage. This stage will use the official +`golangci-lint` image on Docker Hub. + +> [!TIP] +> Because this stage relies on executing an external dependency, it's generally +> a good idea to define the version you want to use as a build argument. This +> lets you more easily manage version upgrades in the future by collocating +> dependency versions to the beginning of the Dockerfile. + +```dockerfile {hl_lines=[2,"6-8"]} +ARG GO_VERSION="1.23" +ARG GOLANGCI_LINT_VERSION="1.61" + +#... + +FROM golangci/golangci-lint:v${GOLANGCI_LINT_VERSION}-alpine AS lint +RUN --mount=target=.,rw \ + golangci-lint run +``` + +Lastly, to enable running both tests simultaneously, you can use the `groups` +construct in the Bake file. A group can specify multiple targets to run with a +single invocation. + +```hcl +group "validate" { + targets = ["test", "lint"] +} +``` + +Now, running both tests is as simple as: + +```console +$ docker buildx bake validate +``` + +## Building variants + +Sometimes you need to build more than one version of a program. The following +example uses Bake to build separate "release" and "debug" variants of the +program, using [matrices](/manuals/build/bake/matrices.md). Using matrices lets +you run parallel builds with different configurations, saving time and ensuring +consistency. + +A matrix expands a single build into multiple builds, each representing a +unique combination of matrix parameters. This means you can orchestrate Bake +into building both the production and development build of your program in +parallel, with minimal configuration changes. + +The example project for this guide is set up to use a build-time option to +conditionally enable debug logging and tracing capabilities. + +- If you compile the program with `go build -tags="debug"`, the additional + logging and tracing capabilities are enabled (development mode). +- If you build without the `debug` tag, the program is compiled with a default + logger (production mode). + +Update the Bake file by adding a matrix attribute which defines the variable +combinations to build: + +```diff {title="docker-bake.hcl"} + target "default" { ++ matrix = { ++ mode = ["release", "debug"] ++ } ++ name = "image-${mode}" + target = "image" +``` + +The `matrix` attribute defines the variants to build ("release" and "debug"). +The `name` attribute defines how the matrix gets expanded into multiple +distinct build targets. In this case, it's relatively simple. The matrix +attribute expands the build into two workflows: `image-release` and +`image-debug`, each using different configuration parameters. + +Next, when building the development variant, we'll pass in a `BUILD_TAGS` +argument with the value of the matrix variable, which we'll later consume in +the Dockerfile. + +```diff {title="docker-bake.hcl"} + target = "image" ++ args = { ++ BUILD_TAGS = mode ++ } + tags = [ +``` + +You'll also want to change how the image tags are assigned to these builds. +Currently, both matrix paths would generate the same image tag names, and +overwrite each other. Update the `tags` attribute use a conditional operator to +set the tag depending on the matrix variable value. + +```diff {title="docker-bake.hcl"} + tags = [ +- "bakeme:latest", ++ mode == "release" ? "bakeme:latest" : "bakeme:dev" + ] +``` + +- If `mode` is `release`, the tag name is `bakeme:latest` +- If `mode` is `debug`, the tag name is `bakeme:dev` + +Finally, update the Dockerfile to consume the `BUILD_TAGS` argument during the +compilation stage. When the `-tags="${BUILD_TAGS}"` option evaluates to +`-tags="debug"`, the compiler uses the `configureLogging` function in the +[`debug.go`](https://github.com/dvdksn/bakeme/blob/75c8a41e613829293c4bd3fc3b4f0c573f458f42/debug.go#L1) +file. + +```diff {title=Dockerfile} + # build compiles the program + FROM base AS build +-ARG TARGETOS TARGETARCH ++ARG TARGETOS TARGETARCH BUILD_TAGS + ENV GOOS=$TARGETOS + ENV GOARCH=$TARGETARCH + RUN --mount=target=. \ + --mount=type=cache,target=/go/pkg/mod \ +- go build -o "/usr/bin/bakeme" . ++ go build -tags="${BUILD_TAGS}" -o "/usr/bin/bakeme" . +``` + +That's all. With these changes, your `docker buildx bake` command now builds +two multi-platform image variants. You can introspect the canonical build +configuration that Bake generates using the `docker buildx bake --print` +command. Running this command shows that Bake will run a `default` group with +two targets with different build arguments and image tags. + +```json {collapse=true} +{ + "group": { + "default": { + "targets": ["image-release", "image-debug"] + } + }, + "target": { + "image-debug": { + "attest": ["type=provenance,mode=max", "type=sbom"], + "context": ".", + "dockerfile": "Dockerfile", + "args": { + "BUILD_TAGS": "debug" + }, + "tags": ["bakeme:dev"], + "target": "image", + "platforms": ["linux/amd64", "linux/arm64", "linux/riscv64"] + }, + "image-release": { + "attest": ["type=provenance,mode=max", "type=sbom"], + "context": ".", + "dockerfile": "Dockerfile", + "args": { + "BUILD_TAGS": "release" + }, + "tags": ["bakeme:latest"], + "target": "image", + "platforms": ["linux/amd64", "linux/arm64", "linux/riscv64"] + } + } +} +``` + +Factoring in all of the platform variants as well, this means that the build +configuration generates 6 different images. + +```console +$ docker buildx bake +$ docker image ls --tree + +IMAGE ID DISK USAGE CONTENT SIZE USED +bakeme:dev f7cb5c08beac 49.3MB 28.9MB +├─ linux/riscv64 0eae8ba0367a 9.18MB 9.18MB +├─ linux/arm64 56561051c49a 30MB 9.89MB +└─ linux/amd64 e8ca65079c1f 9.8MB 9.8MB + +bakeme:latest 20065d2c4d22 44.4MB 25.9MB +├─ linux/riscv64 7cc82872695f 8.21MB 8.21MB +├─ linux/arm64 e42220c2b7a3 27.1MB 8.93MB +└─ linux/amd64 af5b2dd64fde 8.78MB 8.78MB +``` + +## Exporting build artifacts + +Exporting build artifacts like binaries can be useful for deploying to +environments without Docker or Kubernetes. For example, if your programs are +meant to be run on user's local machine. + +> [!TIP] +> The techniques discussed in this section can be applied not only to build +> output like binaries, but to any type of artifacts, such as test reports. + +With programming languages like Go and Rust where the compiled binaries are +usually portable, creating alternate build targets for exporting only the +binary is trivial. All you need to do is add an empty stage in the Dockerfile +containing nothing but the binary that you want to export. + +First, let's add a quick way to build a binary for your local platform and +export it to `./build/local` on the local filesystem. + +In the `docker-bake.hcl` file, create a new `bin` target. In this stage, set +the `output` attribute to a local filesystem path. Buildx automatically detects +that the output looks like a filepath, and exports the results to the specified +path using the [local exporter](/manuals/build/exporters/local-tar.md). + +```hcl +target "bin" { + target = "bin" + output = ["build/bin"] + platforms = ["local"] +} +``` + +Notice that this stage specifies a `local` platform. By default, if `platforms` +is unspecified, builds target the OS and architecture of the BuildKit host. If +you're using Docker Desktop, this often means builds target `linux/amd64` or +`linux/arm64`, even if your local machine is macOS or Windows, because Docker +runs in a Linux VM. Using the `local` platform forces the target platform to +match your local environment. + +Next, add the `bin` stage to the Dockerfile which copies the compiled binary +from the build stage. + +```dockerfile +FROM scratch AS bin +COPY --from=build "/usr/bin/bakeme" / +``` + +Now you can export your local platform version of the binary with `docker +buildx bake bin`. For example, on macOS, this build target generates an +executable in the [Mach-O format](https://en.wikipedia.org/wiki/Mach-O) — the +standard executable format for macOS. + +```console +$ docker buildx bake bin +$ file ./build/bin/bakeme +./build/bin/bakeme: Mach-O 64-bit executable arm64 +``` + +Next, let's add a target to build all of the platform variants of the program. +To do this, you can [inherit](/manuals/build/bake/inheritance.md) the `bin` +target that you just created, and extend it by adding the desired platforms. + +```hcl +target "bin-cross" { + inherits = ["bin"] + platforms = [ + "linux/amd64", + "linux/arm64", + "linux/riscv64", + ] +} +``` + +Now, building the `bin-cross` target creates binaries for all platforms. +Subdirectories are automatically created for each variant. + +```console +$ docker buildx bake bin-cross +$ tree build/ +build/ +└── bin + ├── bakeme + ├── linux_amd64 + │   └── bakeme + ├── linux_arm64 + │   └── bakeme + └── linux_riscv64 + └── bakeme + +5 directories, 4 files +``` + +To also generate "release" and "debug" variants, you can use a matrix just like +you did with the default target. When using a matrix, you also need to +differentiate the output directory based on the matrix value, otherwise the +binary gets written to the same location for each matrix run. + +```hcl +target "bin-all" { + inherits = ["bin-cross"] + matrix = { + mode = ["release", "debug"] + } + name = "bin-${mode}" + args = { + BUILD_TAGS = mode + } + output = ["build/bin/${mode}"] +} +``` + +```console +$ rm -r ./build/ +$ docker buildx bake bin-all +$ tree build/ +build/ +└── bin + ├── debug + │   ├── linux_amd64 + │   │   └── bakeme + │   ├── linux_arm64 + │   │   └── bakeme + │   └── linux_riscv64 + │   └── bakeme + └── release + ├── linux_amd64 + │   └── bakeme + ├── linux_arm64 + │   └── bakeme + └── linux_riscv64 + └── bakeme + +10 directories, 6 files +``` + +## Conclusion + +Docker Buildx Bake streamlines complex build workflows, enabling efficient +multi-platform builds, testing, and artifact export. By integrating Buildx Bake +into your projects, you can simplify your Docker builds, make your build +configuration portable, and wrangle complex configurations more easily. + +Experiment with different configurations and extend your Bake files to match +your project's needs. You might consider integrating Bake into your CI/CD +pipelines to automate builds, testing, and artifact deployment. The flexibility +and power of Buildx Bake can significantly improve your development and +deployment processes. + +### Further reading + +For more information about how to use Bake, check out these resources: + +- [Bake documentation](/manuals/build/bake/_index.md) +- [Matrix targets](/manuals/build/bake/matrices.md) +- [Bake file reference](/manuals/build/bake/reference.md) +- [Bake GitHub Action](https://github.com/docker/bake-action) diff --git a/content/guides/bun/_index.md b/content/guides/bun/_index.md new file mode 100644 index 000000000000..bd015ea6f135 --- /dev/null +++ b/content/guides/bun/_index.md @@ -0,0 +1,34 @@ +--- +description: Containerize and develop Bun applications using Docker. +keywords: getting started, bun +title: Bun language-specific guide +summary: | + Learn how to containerize JavaScript applications with the Bun runtime. +linkTitle: Bun +levels: [beginner] +languages: [js] +params: + time: 10 minutes +--- + +The Bun getting started guide teaches you how to create a containerized Bun application using Docker. In this guide, you'll learn how to: + +> **Acknowledgment** +> +> Docker would like to thank [Pradumna Saraf](https://twitter.com/pradumna_saraf) for his contribution to this guide. + +## What will you learn? + +* Containerize and run a Bun application using Docker +* Set up a local environment to develop a Bun application using containers +* Configure a CI/CD pipeline for a containerized Bun application using GitHub Actions +* Deploy your containerized application locally to Kubernetes to test and debug your deployment + +## Prerequisites + +- Basic understanding of JavaScript is assumed. +- You must have familiarity with Docker concepts like containers, images, and Dockerfiles. If you are new to Docker, you can start with the [Docker basics](/get-started/docker-concepts/the-basics/what-is-a-container.md) guide. + +After completing the Bun getting started modules, you should be able to containerize your own Bun application based on the examples and instructions provided in this guide. + +Start by containerizing an existing Bun application. diff --git a/content/guides/bun/configure-ci-cd.md b/content/guides/bun/configure-ci-cd.md new file mode 100644 index 000000000000..0f614a9c3877 --- /dev/null +++ b/content/guides/bun/configure-ci-cd.md @@ -0,0 +1,131 @@ +--- +title: Configure CI/CD for your Bun application +linkTitle: Configure CI/CD +weight: 40 +keywords: ci/cd, github actions, bun, shiny +description: Learn how to configure CI/CD using GitHub Actions for your Bun application. +aliases: +- /language/bun/configure-ci-cd/ +--- + +## Prerequisites + +Complete all the previous sections of this guide, starting with [Containerize a Bun application](containerize.md). You must have a [GitHub](https://github.com/signup) account and a [Docker](https://hub.docker.com/signup) account to complete this section. + +## Overview + +In this section, you'll learn how to set up and use GitHub Actions to build and test your Docker image as well as push it to Docker Hub. You will complete the following steps: + +1. Create a new repository on GitHub. +2. Define the GitHub Actions workflow. +3. Run the workflow. + +## Step one: Create the repository + +Create a GitHub repository, configure the Docker Hub credentials, and push your source code. + +1. [Create a new repository](https://github.com/new) on GitHub. + +2. Open the repository **Settings**, and go to **Secrets and variables** > + **Actions**. + +3. Create a new **Repository variable** named `DOCKER_USERNAME` and your Docker ID as value. + +4. Create a new [Personal Access Token (PAT)](/manuals/security/for-developers/access-tokens.md#create-an-access-token)for Docker Hub. You can name this token `docker-tutorial`. Make sure access permissions include Read and Write. + +5. Add the PAT as a **Repository secret** in your GitHub repository, with the name + `DOCKERHUB_TOKEN`. + +6. In your local repository on your machine, run the following command to change + the origin to the repository you just created. Make sure you change + `your-username` to your GitHub username and `your-repository` to the name of + the repository you created. + + ```console + $ git remote set-url origin https://github.com/your-username/your-repository.git + ``` + +7. Run the following commands to stage, commit, and push your local repository to GitHub. + + ```console + $ git add -A + $ git commit -m "my commit" + $ git push -u origin main + ``` + +## Step two: Set up the workflow + +Set up your GitHub Actions workflow for building, testing, and pushing the image +to Docker Hub. + +1. Go to your repository on GitHub and then select the **Actions** tab. + +2. Select **set up a workflow yourself**. + + This takes you to a page for creating a new GitHub actions workflow file in + your repository, under `.github/workflows/main.yml` by default. + +3. In the editor window, copy and paste the following YAML configuration and commit the changes. + + ```yaml + name: ci + + on: + push: + branches: + - main + + jobs: + build: + runs-on: ubuntu-latest + steps: + - + name: Login to Docker Hub + uses: docker/login-action@v3 + with: + username: ${{ vars.DOCKER_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + - + name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + - + name: Build and push + uses: docker/build-push-action@v6 + with: + platforms: linux/amd64,linux/arm64 + push: true + tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest + ``` + + For more information about the YAML syntax for `docker/build-push-action`, + refer to the [GitHub Action README](https://github.com/docker/build-push-action/blob/master/README.md). + +## Step three: Run the workflow + +Save the workflow file and run the job. + +1. Select **Commit changes...** and push the changes to the `main` branch. + + After pushing the commit, the workflow starts automatically. + +2. Go to the **Actions** tab. It displays the workflow. + + Selecting the workflow shows you the breakdown of all the steps. + +3. When the workflow is complete, go to your + [repositories on Docker Hub](https://hub.docker.com/repositories). + + If you see the new repository in that list, it means the GitHub Actions + successfully pushed the image to Docker Hub. + +## Summary + +In this section, you learned how to set up a GitHub Actions workflow for your Bun application. + +Related information: + - [Introduction to GitHub Actions](/manuals/build/ci/github-actions/_index.md) + - [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) + +## Next steps + +Next, learn how you can locally test and debug your workloads on Kubernetes before deploying. diff --git a/content/guides/bun/containerize.md b/content/guides/bun/containerize.md new file mode 100644 index 000000000000..ccd52d209981 --- /dev/null +++ b/content/guides/bun/containerize.md @@ -0,0 +1,127 @@ +--- +title: Containerize a Bun application +linkTitle: Containerize your app +weight: 10 +keywords: bun, containerize, initialize +description: Learn how to containerize a Bun application. +aliases: + - /language/bun/containerize/ +--- + +## Prerequisites + +* You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client. + +## Overview + +For a long time, Node.js has been the de-facto runtime for server-side +JavaScript applications. Recent years have seen a rise in new alternative +runtimes in the ecosystem, including [Bun website](https://bun.sh/). Like +Node.js, Bun is a JavaScript runtime. Bun is a comparatively lightweight +runtime that is designed to be fast and efficient. + +Why develop Bun applications with Docker? Having multiple runtimes to choose +from is great. But as the number of runtimes increases, it becomes challenging +to manage the different runtimes and their dependencies consistently across +environments. This is where Docker comes in. Creating and destroying containers +on demand is a great way to manage the different runtimes and their +dependencies. Also, as it's fairly a new runtime, getting a consistent +development environment for Bun can be challenging. Docker can help you set up +a consistent development environment for Bun. + +## Get the sample application + +Clone the sample application to use with this guide. Open a terminal, change +directory to a directory that you want to work in, and run the following +command to clone the repository: + +```console +$ git clone https://github.com/Pradumnasaraf/bun-docker.git +``` + +You should now have the following contents in your `bun-docker` directory. + +```text +├── bun-docker/ +│ ├── compose.yml +│ ├── Dockerfile +│ ├── LICENSE +│ ├── server.js +│ └── README.md +``` + +In the Dockerfile, you'll notice that the `FROM` instruction uses `oven/bun` +as the base image. This is the official image for Bun created by Oven, the +company behind Bun. This image is [available on the Docker Hub](https://hub.docker.com/r/oven/bun). + +```dockerfile +# Use the Bun image as the base image +FROM oven/bun:latest + +# Set the working directory in the container +WORKDIR /app + +# Copy the current directory contents into the container at /app +COPY . . + +# Expose the port on which the API will listen +EXPOSE 3000 + +# Run the server when the container launches +CMD ["bun", "server.js"] +``` + +Aside from specifying `oven/bun` as the base image, this Dockerfile also: + +- Sets the working directory in the container to `/app` +- Copies the contents of the current directory to the `/app` directory in the container +- Exposes port 3000, where the API is listening for requests +- And finally, starts the server when the container launches with the command `bun server.js`. + +## Run the application + +Inside the `bun-docker` directory, run the following command in a terminal. + +```console +$ docker compose up --build +``` + +Open a browser and view the application at [http://localhost:3000](http://localhost:3000). You will see a message `{"Status" : "OK"}` in the browser. + +In the terminal, press `ctrl`+`c` to stop the application. + +### Run the application in the background + +You can run the application detached from the terminal by adding the `-d` +option. Inside the `bun-docker` directory, run the following command +in a terminal. + +```console +$ docker compose up --build -d +``` + +Open a browser and view the application at [http://localhost:3000](http://localhost:3000). + + +In the terminal, run the following command to stop the application. + +```console +$ docker compose down +``` + +## Summary + +In this section, you learned how you can containerize and run your Bun +application using Docker. + +Related information: + + - [Dockerfile reference](/reference/dockerfile.md) + - [.dockerignore file](/reference/dockerfile.md#dockerignore-file) + - [Docker Compose overview](/manuals/compose/_index.md) + - [Compose file reference](/reference/compose-file/_index.md) + +## Next steps + +In the next section, you'll learn how you can develop your application using +containers. diff --git a/content/guides/bun/deploy.md b/content/guides/bun/deploy.md new file mode 100644 index 000000000000..7659c97fd910 --- /dev/null +++ b/content/guides/bun/deploy.md @@ -0,0 +1,141 @@ +--- +title: Test your Bun deployment +linkTitle: Test your deployment +weight: 50 +keywords: deploy, kubernetes, bun +description: Learn how to develop locally using Kubernetes +aliases: +- /language/bun/deploy/ +--- + +## Prerequisites + +- Complete all the previous sections of this guide, starting with [Containerize a Bun application](containerize.md). +- [Turn on Kubernetes](/desktop/kubernetes/#install-and-turn-on-kubernetes) in Docker Desktop. + +## Overview + +In this section, you'll learn how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. This allows you to test and debug your workloads on Kubernetes locally before deploying. + +## Create a Kubernetes YAML file + +In your `bun-docker` directory, create a file named +`docker-kubernetes.yml`. Open the file in an IDE or text editor and add +the following contents. Replace `DOCKER_USERNAME/REPO_NAME` with your Docker +username and the name of the repository that you created in [Configure CI/CD for +your Bun application](configure-ci-cd.md). + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: docker-bun-demo + namespace: default +spec: + replicas: 1 + selector: + matchLabels: + app: bun-api + template: + metadata: + labels: + app: bun-api + spec: + containers: + - name: bun-api + image: DOCKER_USERNAME/REPO_NAME + imagePullPolicy: Always +--- +apiVersion: v1 +kind: Service +metadata: + name: service-entrypoint + namespace: default +spec: + type: NodePort + selector: + app: bun-api + ports: + - port: 3000 + targetPort: 3000 + nodePort: 30001 +``` + +In this Kubernetes YAML file, there are two objects, separated by the `---`: + + - A Deployment, describing a scalable group of identical pods. In this case, + you'll get just one replica, or copy of your pod. That pod, which is + described under `template`, has just one container in it. The + container is created from the image built by GitHub Actions in [Configure CI/CD for + your Bun application](configure-ci-cd.md). + - A NodePort service, which will route traffic from port 30001 on your host to + port 3000 inside the pods it routes to, allowing you to reach your app + from the network. + +To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/). + +## Deploy and check your application + +1. In a terminal, navigate to `bun-docker` and deploy your application to + Kubernetes. + + ```console + $ kubectl apply -f docker-kubernetes.yml + ``` + + You should see output that looks like the following, indicating your Kubernetes objects were created successfully. + + ```text + deployment.apps/docker-bun-demo created + service/service-entrypoint created + ``` + +2. Make sure everything worked by listing your deployments. + + ```console + $ kubectl get deployments + ``` + + Your deployment should be listed as follows: + + ```shell + NAME READY UP-TO-DATE AVAILABLE AGE + docker-bun-demo 1/1 1 1 10s + ``` + + This indicates all one of the pods you asked for in your YAML are up and running. Do the same check for your services. + + ```console + $ kubectl get services + ``` + + You should get output like the following. + + ```shell + NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE + kubernetes ClusterIP 10.96.0.1 443/TCP 88m + service-entrypoint NodePort 10.105.145.223 3000:30001/TCP 83s + ``` + + In addition to the default `kubernetes` service, you can see your `service-entrypoint` service, accepting traffic on port 30001/TCP. + +3. In a browser, visit the following address. You should see the message `{"Status" : "OK"}`. + + ```console + http://localhost:30001/ + ``` + +4. Run the following command to tear down your application. + + ```console + $ kubectl delete -f docker-kubernetes.yml + ``` + +## Summary + +In this section, you learned how to use Docker Desktop to deploy your Bun application to a fully-featured Kubernetes environment on your development machine. + +Related information: + - [Kubernetes documentation](https://kubernetes.io/docs/home/) + - [Deploy on Kubernetes with Docker Desktop](/manuals/desktop/kubernetes.md) + - [Swarm mode overview](/manuals/engine/swarm/_index.md) diff --git a/content/guides/bun/develop.md b/content/guides/bun/develop.md new file mode 100644 index 000000000000..bb3c6b390cee --- /dev/null +++ b/content/guides/bun/develop.md @@ -0,0 +1,75 @@ +--- +title: Use containers for Bun development +linkTitle: Develop your app +weight: 20 +keywords: bun, local, development +description: Learn how to develop your Bun application locally. +aliases: +- /language/bun/develop/ +--- + +## Prerequisites + +Complete [Containerize a Bun application](containerize.md). + +## Overview + +In this section, you'll learn how to set up a development environment for your containerized application. This includes: + +- Configuring Compose to automatically update your running Compose services as you edit and save your code + +## Get the sample application + +Clone the sample application to use with this guide. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository: + +```console +$ git clone https://github.com/Pradumnasaraf/bun-docker.git +``` + +## Automatically update services + +Use Compose Watch to automatically update your running Compose services as you +edit and save your code. For more details about Compose Watch, see [Use Compose +Watch](/manuals/compose/how-tos/file-watch.md). + +Open your `compose.yml` file in an IDE or text editor and then add the Compose Watch instructions. The following example shows how to add Compose Watch to your `compose.yml` file. + +```yaml {hl_lines="9-12",linenos=true} +services: + server: + image: bun-server + build: + context: . + dockerfile: Dockerfile + ports: + - "3000:3000" + develop: + watch: + - action: rebuild + path: . +``` + +Run the following command to run your application with Compose Watch. + +```console +$ docker compose watch +``` + +Now, if you modify your `server.js` you will see the changes in real time without re-building the image. + +To test it out, open the `server.js` file in your favorite text editor and change the message from `{"Status" : "OK"}` to `{"Status" : "Updated"}`. Save the file and refresh your browser at `http://localhost:3000`. You should see the updated message. + +Press `ctrl+c` in the terminal to stop your application. + +## Summary + +In this section, you also learned how to use Compose Watch to automatically rebuild and run your container when you update your code. + +Related information: + - [Compose file reference](/reference/compose-file/) + - [Compose file watch](/manuals/compose/how-tos/file-watch.md) + - [Multi-stage builds](/manuals/build/building/multi-stage.md) + +## Next steps + +In the next section, you'll take a look at how to set up a CI/CD pipeline using GitHub Actions. diff --git a/content/guides/container-supported-development.md b/content/guides/container-supported-development.md new file mode 100644 index 000000000000..52879478303a --- /dev/null +++ b/content/guides/container-supported-development.md @@ -0,0 +1,76 @@ +--- +title: "Faster development and testing with container-supported development" +linkTitle: Container-supported development +summary: | + Containers don't have to be just for your app. Learn how to run your app's dependent services and other debugging tools to enhance your development environment. +description: | + Use containers in your local development loop to develop and test faster… even if your main app isn't running in containers. +levels: [beginner] +params: + image: images/learning-paths/container-supported-development.png + time: 20 minutes + resource_links: [] +--- + +Containers offer a consistent way to build, share, and run applications across different environments. While containers are typically used to containerize your application, they also make it incredibly easy to run essential services needed for development. Instead of installing or connecting to a remote database, you can easily launch your own database. But the possibilities don't stop there. + +With container-supported development, you use containers to enhance your development environment by emulating or running your own instances of the services your app needs. This provides faster feedback loops, less coupling with remote services, and a greater ability to test error states. + +And best of all, you can have these benefits regardless of whether the main app under development is running in containers. + +## What you'll learn + +- The meaning of container-supported development +- How to connect non-containerized applications to containerized services +- Several examples of using containers to emulate or run local instances of services +- How to use containers to add additional troubleshooting and debugging tools to your development environment + +## Who's this for? + +- Teams that want to reduce the coupling they have on shared or deployed infrastructure or remote API endpoints +- Teams that want to reduce the complexity and costs associated with using cloud services directly during development +- Developers that want to make it easier to visualize what's going on in their databases, queues, etc. +- Teams that want to reduce the complexity of setting up their development environment without impacting the development of the app itself + + +## Tools integration + +Works well with Docker Compose and Testcontainers. + +## Modules + +### What is container-supported development? + +Container-supported development is the idea of using containers to enhance your development environment by running local instances or emulators of the services your application relies on. Once you're using containers, it's easy to add additional services to visualize or troubleshoot what's going on in your services. + +{{< youtube-embed pNcrto_wGi0 >}} + +### Demo: running databases locally + +With container-supported development, it's easy to run databases locally. In this demo, you'll see how to do so, as well as how to connect a non-containerized application to the database. + +{{< youtube-embed VieWeXOwKLU >}} + +### Demo: mocking API endpoints + +Many APIs require data from other data endpoints. In development, this adds complexities such as the sharing of credentials, uptime/availability, and rate limiting. Instead of relying on those services directly, your application can interact with a mock API server. + +This demo will demonstrate how using WireMock can make it easy to develop and test an application, including the APIs various error states. + +{{< youtube-embed VXSmX6f8vo0 >}} + +### Demo: developing the cloud locally + +When developing apps, it's often easier to outsource aspects of the application to cloud services, such as Amazon S3. However, connecting to those services in local development introduces IAM policies, networking constraints, and provisioning complications. While these requirements are important in a production setting, they complicate development environments significantly. + +With container-supported development, you can run local instances of these services during development and testing, removing the need for complex setups. In this demo, you'll see how LocalStack makes it easy to develop and test applications entirely from the developer's workstation. + +{{< youtube-embed JtwUMvR5xlY >}} + +### Demo: adding additional debug and troubleshooting tools + +Once you start using containers in your development environment, it becomes much easier to add additional containers to visualize the contents of the databases or message queues, seed document stores, or event publishers. In this demo, you'll see a few of these examples, as well as how you can connect multiple containers together to make testing even easier. + +{{< youtube-embed TCZX15aKSu4 >}} + +
\ No newline at end of file diff --git a/content/manuals/admin/organization/activity-logs.md b/content/manuals/admin/organization/activity-logs.md index 3409fbf52969..97e42f25ad0c 100644 --- a/content/manuals/admin/organization/activity-logs.md +++ b/content/manuals/admin/organization/activity-logs.md @@ -66,6 +66,9 @@ Refer to the following section for a list of events and their descriptions: | Single Sign-On domain added | Details of the single sign-on domain added to your organization | | Single Sign-On domain removed | Details of the single sign-on domain removed from your organization | | Single Sign-On domain verified | Details of the single sign-on domain verified for your organization | +| Access token created | Access token created in organization | +| Access token updated | Access token updated in organization | +| Access token deleted | Access token deleted in organization | ### Repository events diff --git a/content/manuals/admin/organization/insights.md b/content/manuals/admin/organization/insights.md index a991ecb0a70f..29b6f44f3e45 100644 --- a/content/manuals/admin/organization/insights.md +++ b/content/manuals/admin/organization/insights.md @@ -2,14 +2,8 @@ description: Gain insights about your organization's users and their Docker usage. keywords: organization, insights title: Insights -sitemap: false --- -{{% restricted title="Early Access" %}} -Insights is an [early access](/release-lifecycle#early-access-ea) feature and -is only available to those in the early access feedback program. -{{% /restricted %}} - > [!NOTE] > Insights requires a [Docker Business > subscription](/subscription/core-subscription/details/#docker-business) and diff --git a/content/manuals/build-cloud/setup.md b/content/manuals/build-cloud/setup.md index cbf4098c7bb7..9d8ef75ab08b 100644 --- a/content/manuals/build-cloud/setup.md +++ b/content/manuals/build-cloud/setup.md @@ -70,6 +70,16 @@ The builder has native support for the `linux/amd64` and `linux/arm64` architectures. This gives you a high-performance build cluster for building multi-platform images natively. +## Firewall configuration + +To use Docker Build Cloud behind a firewall, ensure that your firewall allows +traffic to the following addresses: + +- 3.211.38.21 +- https://auth.docker.io +- https://build-cloud.docker.com +- https://hub.docker.com + ## What's next - See [Building with Docker Build Cloud](usage.md) for examples on how to use Docker Build Cloud. diff --git a/content/manuals/build/bake/variables.md b/content/manuals/build/bake/variables.md index 1dfa803900df..b584cc1483a2 100644 --- a/content/manuals/build/bake/variables.md +++ b/content/manuals/build/bake/variables.md @@ -78,6 +78,35 @@ $ docker buildx bake --print } ``` +## Escape variable interpolation + +If you want to bypass variable interpolation when parsing the Bake definition, +use double dollar signs (`$${VARIABLE}`). + +```hcl +target "default" { + dockerfile-inline = <`. You can customize how the secrets get mounted in the build container using the `target` and `env` options for the `RUN --mount` flag in diff --git a/content/manuals/build/ci/github-actions/configure-builder.md b/content/manuals/build/ci/github-actions/configure-builder.md index a02c83a80ac9..4d6bd1c981a6 100644 --- a/content/manuals/build/ci/github-actions/configure-builder.md +++ b/content/manuals/build/ci/github-actions/configure-builder.md @@ -67,12 +67,12 @@ Logs will be available at the end of a job: You can provide a [BuildKit configuration](../../buildkit/toml-configuration.md) to your builder if you're using the [`docker-container` driver](/manuals/build/builders/drivers/docker-container.md) -(default) with the `config` or `config-inline` inputs: +(default) with the `config` or `buildkitd-config-inline` inputs: ### Registry mirror You can configure a registry mirror using an inline block directly in your -workflow with the `config-inline` input: +workflow with the `buildkitd-config-inline` input: ```yaml name: ci @@ -87,7 +87,7 @@ jobs: - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 with: - config-inline: | + buildkitd-config-inline: | [registry."docker.io"] mirrors = ["mirror.gcr.io"] ``` @@ -99,7 +99,7 @@ For more information about using a registry mirror, see [Registry mirror](../../ You can limit the parallelism of the BuildKit solver which is particularly useful for low-powered machines. -You can use the `config-inline` input like the previous example, or you can use +You can use the `buildkitd-config-inline` input like the previous example, or you can use a dedicated BuildKit config file from your repository if you want with the `config` input: diff --git a/content/manuals/compose/how-tos/environment-variables/envvars.md b/content/manuals/compose/how-tos/environment-variables/envvars.md index 8531e7072165..05196b5ce4d1 100644 --- a/content/manuals/compose/how-tos/environment-variables/envvars.md +++ b/content/manuals/compose/how-tos/environment-variables/envvars.md @@ -31,8 +31,7 @@ This page contains information on how you can set or change the following pre-de ## Methods to override You can set or change the pre-defined environment variables: -- Within your Compose file using the [`environment` attribute](set-environment-variables.md#use-the-environment-attribute) -- With the `env-file` attribute and an [environment file](set-environment-variables.md#use-the-env_file-attribute) +- With an [`.env` file located in your working director](/manuals/compose/how-tos/environment-variables/variable-interpolation.md) - From the command line - From your [shell](variable-interpolation.md#substitute-from-the-shell) diff --git a/content/manuals/compose/how-tos/environment-variables/set-environment-variables.md b/content/manuals/compose/how-tos/environment-variables/set-environment-variables.md index cdf70b2009da..55db221e9e3d 100644 --- a/content/manuals/compose/how-tos/environment-variables/set-environment-variables.md +++ b/content/manuals/compose/how-tos/environment-variables/set-environment-variables.md @@ -68,7 +68,7 @@ services: env_file: "webapp.env" ``` -Using an `.env` file lets you to use the same file for use by a plain `docker run --env-file ...` command, or to share the same `.env` file within multiple services without the need to duplicate a long `environment` YAML block. +Using an `.env` file lets you use the same file for use by a plain `docker run --env-file ...` command, or to share the same `.env` file within multiple services without the need to duplicate a long `environment` YAML block. It can also help you keep your environment variables separate from your main configuration file, providing a more organized and secure way to manage sensitive information, as you do not need to place your `.env` file in the root of your project's directory. @@ -85,7 +85,6 @@ The paths to your `.env` file, specified in the `env_file` attribute, are relati ### Additional information - If multiple files are specified, they are evaluated in order and can override values set in previous files. -- In addition, as the `.env` file supports [interpolation](variable-interpolation.md), it is possible to combine those with values set by `environment`. - As of Docker Compose version 2.24.0, you can set your `.env` file, defined by the `env_file` attribute, to be optional by using the `required` field. When `required` is set to `false` and the `.env` file is missing, Compose silently ignores the entry. ```yaml env_file: diff --git a/content/manuals/desktop/faqs/general.md b/content/manuals/desktop/faqs/general.md index c228c6a342f9..6fbdaa921f4f 100644 --- a/content/manuals/desktop/faqs/general.md +++ b/content/manuals/desktop/faqs/general.md @@ -65,3 +65,40 @@ For more information and examples, see [how to connect from a container to a ser It is not possible to pass through a USB device (or a serial port) to a container as it requires support at the hypervisor level. + +### How do I run Docker Desktop without administrator privileges? + +Docker Desktop requires administrator privileges only for installation. Once installed, administrator privileges are not needed to run it. However, for non-admin users to run Docker Desktop, it must be installed using a specific installer flag and meet certain prerequisites, which vary by platform. + +{{< tabs >}} +{{< tab name="Mac" >}} + +To run Docker Desktop on Mac without requiring administrator privileges, install via the command line and pass the `—user=` installer flag: + +```console +$ /Applications/Docker.app/Contents/MacOS/install --user= +``` + +You can then sign in to your machine with the user ID specified, and launch Docker Desktop. + +> [!NOTE] +> +> Before launching Docker Desktop, if a `settings.json` file already exists in the `~/Library/Group Containers/group.com.docker/` directory, you will see a **Finish setting up Docker Desktop** window that prompts for administrator privileges when you select **Finish**. To avoid this, ensure you delete the `settings.json` file left behind from any previous installations before launching the application. + +{{< /tab >}} +{{< tab name="Windows" >}} + +> [!NOTE] +> +> If you are using the WSL 2 backend, first make sure that you meet the [minimum required version](/manuals/desktop/wsl/best-practices.md) for WSL 2. Otherwise, update WSL 2 first. + +To run Docker Desktop on Windows without requiring administrator privileges, install via the command line and pass the `—always-run-service` installer flag. + +```console +$ "Docker Desktop Installer.exe" install —always-run-service +``` + +{{< /tab >}} +{{< /tabs >}} + + diff --git a/content/manuals/desktop/install/mac-install.md b/content/manuals/desktop/install/mac-install.md index d6d743afbc88..47379f9f4383 100644 --- a/content/manuals/desktop/install/mac-install.md +++ b/content/manuals/desktop/install/mac-install.md @@ -63,6 +63,10 @@ This page contains download URLs, information about system requirements, and ins ## Install and run Docker Desktop on Mac +> [!TIP] +> +> See the [FAQs](/manuals/desktop/faqs/general.md#how-do-I-run-docker-desktop-without-administrator-privileges) on how to install and run Docker Desktop without needing administrator privileges. + ### Install interactively 1. Download the installer using the download buttons at the top of the page, or from the [release notes](../release-notes.md). diff --git a/content/manuals/desktop/install/windows-install.md b/content/manuals/desktop/install/windows-install.md index 1537e2c845b4..d1e8beff42a4 100644 --- a/content/manuals/desktop/install/windows-install.md +++ b/content/manuals/desktop/install/windows-install.md @@ -164,6 +164,10 @@ again when you switch back. ## Install Docker Desktop on Windows +> [!TIP] +> +> See the [FAQs](/manuals/desktop/faqs/general.md#how-do-I-run-docker-desktop-without-administrator-privileges) on how to install and run Docker Desktop without needing administrator privileges. + ### Install interactively 1. Download the installer using the download button at the top of the page, or from the [release notes](../release-notes.md). diff --git a/content/manuals/desktop/troubleshoot/_index.md b/content/manuals/desktop/troubleshoot/_index.md index ad96e25c3183..c0ebc8863996 100644 --- a/content/manuals/desktop/troubleshoot/_index.md +++ b/content/manuals/desktop/troubleshoot/_index.md @@ -21,9 +21,12 @@ weight: 160 This page contains information on how to diagnose and troubleshoot Docker Desktop, and how to check the logs. -## Troubleshooting menu +## Troubleshoot menu -Select the **Question mark** icon near the top-right corner of Docker Dashboard, then **Troubleshooting**. +To navigate to **Troubleshoot** either: + +- Select the Docker menu Docker menu {{< inline-image src="../images/whale-x.svg" alt="whale menu" >}} and then **Troubleshoot**. +- Select the **Troubleshoot** icon near the top-right corner of Docker Dashboard. The **Troubleshooting** menu contains the following options: @@ -39,8 +42,6 @@ Docker Desktop to their initial state, the same as when Docker Desktop was first If you are a Mac or Linux user, you also have the option to **Uninstall** Docker Desktop from your system. -You can also access these troubleshoot options from the Docker menu {{< inline-image src="../images/whale-x.svg" alt="whale menu" >}}. - > [!TIP] > > If you need to contact support, select the **Question mark** icon near the top-right corner of Docker Dashboard, and then select **Contact support**. Users with a paid Docker subscription can use this option to send a support request. @@ -57,22 +58,22 @@ You can also access these troubleshoot options from the Docker menu {{< inline-i ### Diagnose from the app -1. Select the **Question mark** icon near the top-right corner of Docker Dashboard, then **Report a bug** -This opens a new in-app page and starts collecting the diagnostics. -2. When the diagnostics collection process is complete Docker Desktop prints a diagnostic ID. Copy this ID. -3. Use your diagnostics ID to get help: - - If you have a paid Docker subscription, select **Contact support** from the **Troubleshooting** menu. This opens the Docker Desktop support form. Fill in the information required. Your diagnostics ID is gathered automatically. Then, select **Submit ticket** to request Docker Desktop support. +1. From **Troubleshoot**, select **Get support**. This opens the in-app Support page and starts collecting the diagnostics. +2. When the diagnostics collection process is complete, select **Upload to get a Diagnostic ID**. +3. When the diagnostics are uploaded, Docker Desktop prints a diagnostic ID. Copy this ID. +4. Use your diagnostics ID to get help: + - If you have a paid Docker subscription, select **Contact support**. This opens the Docker Desktop support form. Fill in the information required and add the ID you copied in step three to the **Diagnostics ID field**. Then, select **Submit ticket** to request Docker Desktop support. > [!NOTE] > > You must be signed in to Docker Desktop to access the support form. For information on what's covered as part of Docker Desktop support, see [Support](../../support/_index.md). - - If you don't have a paid Docker subscription, follow the GitHub repository link to open a new Docker Desktop issue on GitHub. Complete the information required on the GitHub issue and ensure you add the diagnostic ID printed in step two. + - If you don't have a paid Docker subscription, select **Report a Bug** to open a new Docker Desktop issue on GitHub. Complete the information required and ensure you add the diagnostic ID you copied in step three. ### Diagnose from an error message 1. When an error message appears, select **Gather diagnostics**. 2. When the diagnostics are uploaded, Docker Desktop prints a diagnostic ID. Copy this ID. 3. Use your diagnostics ID to get help: - - Select **Contact support** from the **Troubleshooting** menu. This opens the Docker Desktop support form. Fill in the information required. Your diagnostics ID is gathered automatically. Then, select **Submit ticket** to request Docker Desktop support. + - If you have a paid Docker subscription, select **Contact support**. This opens the Docker Desktop support form. Fill in the information required and add the ID you copied in step three to the **Diagnostics ID field**. Then, select **Submit ticket** to request Docker Desktop support. > [!NOTE] > > You must be signed in to Docker Desktop to access the support form. For information on what's covered as part of Docker Desktop support, see [Support](../../support/_index.md). @@ -177,7 +178,7 @@ $ unzip –l /tmp/.zip #### Use your diagnostics ID to get help -Select **Contact support** from the **Troubleshooting** menu. This opens the Docker Desktop support form. Fill in the information required. Your diagnostics ID is gathered automatically. Then, select **Submit ticket** to request Docker Desktop support. +If you have a paid Docker subscription, select **Contact support**. This opens the Docker Desktop support form. Fill in the information required and add the ID you copied in step three to the **Diagnostics ID field**. Then, select **Submit ticket** to request Docker Desktop support. If you don't have a paid Docker subscription, create an issue on GitHub: diff --git a/content/manuals/docker-hub/download-rate-limit.md b/content/manuals/docker-hub/download-rate-limit.md index c0bca10b5c85..82afc75af2a7 100644 --- a/content/manuals/docker-hub/download-rate-limit.md +++ b/content/manuals/docker-hub/download-rate-limit.md @@ -50,7 +50,7 @@ The file contains the following comma separated values. | `datehour` | The date and hour (`yyyy/mm/dd/hh`) of the pull that resulted in the data transfer. | This helps in identifying peak usage times and patterns. | | `user_name` | The Docker ID of the user that pulled the image | This lets organization owners track data consumption per user and manage resources effectively. | | `repository` | The name of the repository of the image that was pulled. | This lets you identify which repositories are most frequently accessed and consume most of the data transfer. | -| `pat_name` | Name of the personal access token that was used for authentication with Docker CLI. `generated` tokens are automatically generated by the Docker client when a user signs in. | Personal access tokens are usually used to authenticate automated tools (Docker Desktop, CI/CD tools, etc.). This is useful for identifying which automated system issued the pull. | +| `access_token_name` | Name of the access token that was used for authentication with Docker CLI. `generated` tokens are automatically generated by the Docker client when a user signs in. | Personal access tokens are usually used to authenticate automated tools (Docker Desktop, CI/CD tools, etc.). This is useful for identifying which automated system issued the pull. | | `ips` | The IP address that was used to pull the image. This field is aggregated, so more than one IP address may appear, representing all the IPs used to pull an image within the same date and hour. | This helps you understand the origin of the data transfer, which is useful for diagnosing and identifying patterns in automated or manual pulls. | | `repository_privacy` | The privacy state of the image repository that was pulled. This can either be `public` or `private`. | This distinguishes between public and private repositories to identify which data transfer threshold the pull impacts. | | `tag` | The tag for the image. The tag is only available if the pull request included a tag. | This helps in identifying the image. Tags are often used to identify specific versions or variants of an image. | diff --git a/content/manuals/docker-hub/release-notes.md b/content/manuals/docker-hub/release-notes.md index 30c2440fdb44..9e402191cd29 100644 --- a/content/manuals/docker-hub/release-notes.md +++ b/content/manuals/docker-hub/release-notes.md @@ -254,7 +254,7 @@ Each organization page now breaks down into these tabs: ### New features -* You can now [create personal access tokens](access-tokens.md) in Docker Hub and use them to authenticate from the Docker CLI. Find them in your account settings, under the new **[Security](https://hub.docker.com/settings/security)** section. +* You can now [create personal access tokens](/security/for-developers/access-tokens/) in Docker Hub and use them to authenticate from the Docker CLI. Find them in your account settings, under the new **[Security](https://hub.docker.com/settings/security)** section. ### Known Issues diff --git a/content/manuals/docker-hub/service-accounts.md b/content/manuals/docker-hub/service-accounts.md index b8c43a5dc37c..9237220d091a 100644 --- a/content/manuals/docker-hub/service-accounts.md +++ b/content/manuals/docker-hub/service-accounts.md @@ -11,6 +11,10 @@ weight: 50 > > Service accounts require a > [Docker Team, or Business subscription](../subscription/_index.md). +> +> Docker recommends that you use organization access tokens instead of service +> accounts. For more details, see [Organization access +> tokens](/security/for-admins/access-tokens/). A service account is a Docker ID used for automated management of container images or containerized applications. Service accounts are typically used in automated workflows, and don't share Docker IDs with the members in the organization. Common use cases for service accounts include mirroring content on Docker Hub, or tying in image pulls from your CI/CD process. @@ -49,7 +53,7 @@ To create a new service account for your Team account: 2. Create a [team](manage-a-team.md) in your organization and grant it read-only access to your private repositories. 3. Add the new Docker ID to your [organization](orgs.md). 4. Add the new Docker ID to the [team](manage-a-team.md) you created earlier. -5. Create a new [personal access token (PAT)](access-tokens.md) from the user account and use it for CI. +5. Create a new [personal access token (PAT)](/security/for-developers/access-tokens/) from the user account and use it for CI. > [!NOTE] > diff --git a/content/manuals/engine/cli/completion.md b/content/manuals/engine/cli/completion.md index 6c0f2c59167e..ac8fe44eb4bb 100644 --- a/content/manuals/engine/cli/completion.md +++ b/content/manuals/engine/cli/completion.md @@ -89,8 +89,8 @@ $ docker completion zsh > ~/.docker/completions/_docker ``` ```console -$ cat <> ~/.zshrc -fpath=(~/.docker/completions \\$fpath) +$ cat <<"EOT" >> ~/.zshrc +FPATH="$HOME/.docker/completions:$FPATH" autoload -Uz compinit compinit EOT diff --git a/content/manuals/harmonia/_index.md b/content/manuals/harmonia/_index.md index 3172749f951c..ed42d5089104 100644 --- a/content/manuals/harmonia/_index.md +++ b/content/manuals/harmonia/_index.md @@ -49,13 +49,21 @@ To verify creation, check the context switcher in the top-left corner of the Doc Run the following command: ```console -$ docker harmonia engine create cloudengine --arch "amd64" --use +$ docker harmonia engine create cloudengine --type "standard-amd64" --use ``` This creates an engine called `cloudengine` and: - Immediately switches you to the new cloud engine with the `--use` flag. -- Sets the engine's CPU architecture to amd64 using the `--arch "amd64"` flag. You can choose between amd64 and arm64. -- Configures the engine size with the `--size "standard"` flag. Options are standard (2 CPU cores, 4GB RAM, default) or large (4 CPU cores, 8GB RAM). +- Sets the engine size to standard and the engine's CPU architecture to amd64 with the `--type` flag. + +Project Harmonia supports the following values for `--type`: +- `standard-arm64` +- `standard-amd64` (default) +- `large-arm64` +- `large-amd64` +- `aiml-amd64` + +Standard size engines have 2 CPU cores and 4GB RAM, large and AI/ML engines have 4 CPU cores and 8GB RAM. To verify you're using the newly created cloud engine, run: diff --git a/content/manuals/security/for-admins/access-tokens.md b/content/manuals/security/for-admins/access-tokens.md new file mode 100644 index 000000000000..87dcc000fe64 --- /dev/null +++ b/content/manuals/security/for-admins/access-tokens.md @@ -0,0 +1,120 @@ +--- +title: Organization access tokens +description: Learn how to create and manage organization access tokens + to securely push and pull images programmatically. +keywords: docker hub, security, OAT, organization access token +linkTitle: Organization access tokens (Beta) +--- + +{{% experimental title="Beta" %}} +The organization access tokens feature is currently in [Beta](../../release-lifecycle.md#beta). +{{% /experimental %}} + +> [!WARNING] +> +> Organization access tokens aren't currently compatible with Docker Build Cloud. If you +> are using Docker Build Cloud, you must use personal access tokens instead. + +An organization access token (OAT) is like a [personal access token +(PAT)](/security/for-developers/access-tokens/), but an OAT is associated with +an organization and not a single user account. Use an OAT instead of a PAT to +let business-critical tasks access Docker Hub repositories without connecting +the token to single user. You must have a [Docker Team or Business +subscription](/subscription/core-subscription/details/) to use OATs. + +OATs provide the following advantages: + +- You can investigate when the OAT was last used and then disable or delete it + if you find any suspicious activity. +- You can limit what each OAT has access to, which limits the impact if an OAT + is compromised. +- All organization owners can manage OATs. If one owner leaves the organization, + the remaining owners can still manage the OATs. +- OATs have their own Docker Hub usage limits that don't count towards your + personal account's limits. + +If you have existing [service accounts](/docker-hub/service-accounts/), Docker recommends that you replace the service accounts with OATs. OATs offer the following advantages over service accounts: + +- Access permissions are easier to manage with OATs. You can assign access + permissions to OATs, while service accounts require using teams for access + permissions. +- OATs are easier to manage. OATs are centrally managed in the Admin Console. + For service accounts, you may need to sign in to that service account to + manage it. If using single sign-on enforcement and the service account is not + in your IdP, you may not be able to sign in to the service account to manage + it. +- OATs are not associated with a single user. If a user with access to the + service account leaves your organization, you may lose access to the service + account. OATs can be managed by any organization owner. + +## Create an organization access token + +> [!IMPORTANT] +> +> Treat access tokens like a password and keep them secret. Store your tokens securely in a credential manager for example. + +Organization owners can create up to 10 organization access tokens (OATs) for +organizations with a Team subscription and up to 100 OATs for organizations with +a Business subscription. Expired tokens count towards the total amount of +tokens. + +To create an OAT: + +1. Sign in to the [Admin Console](https://app.docker.com/admin). + +2. Select the organization you want to create an access token for. + +3. Under **Security and access**, select **Access tokens**. + +4. Select **Generate access token**. + +5. Add a label and optional description for your token. Use something that indicates the use case or purpose of the token. + +6. Select the expiration date for the token. + +7. Select the repository access for the token. + + The access permissions are scopes that set restrictions in your repositories. + For example, for Read & Write permissions, an automation pipeline can build + an image and then push it to a repository. However, it can't delete the + repository. You can select one of the following options: + + - **Public repositories (read only)** + - **All repositories**: You can select read access, or read and write access. + - **Select repositories**: You can select up to 50 repositories, and then + select read access, or read and write access for each repository. + +8. Select **Generate token** and then copy the token that appears on the screen + and save it. You won't be able to retrieve the token once you exit the + screen. + +## Use an organization access token + +You can use an organization access token when you sign in using Docker CLI. + +Sign in from your Docker CLI client with the following command, replacing +`YOUR_ORG` with your organization name: + +```console +$ docker login --username +``` + +When prompted for a password, enter your organization access token instead of a +password. + +## Modify existing tokens + +You can rename, update the description, update the repository access, +deactivate, or delete a token as needed. + +1. Sign in to the [Admin Console](https://app.docker.com/admin). + +2. Select the organization you want to modify an access token for. + +3. Under **Security and access**, select **Access tokens**. + +4. Select the actions menu on the far right of a token row, then select + **Deactivate**, **Edit**, or **Delete** to modify the token. For **Inactive** + tokens, you can only select **Delete**. + +5. If editing a token, select **Save** after specifying your modifications. diff --git a/content/manuals/security/for-admins/single-sign-on/connect/_index.md b/content/manuals/security/for-admins/single-sign-on/connect.md similarity index 93% rename from content/manuals/security/for-admins/single-sign-on/connect/_index.md rename to content/manuals/security/for-admins/single-sign-on/connect.md index 676a95bcc32b..5096e986650a 100644 --- a/content/manuals/security/for-admins/single-sign-on/connect/_index.md +++ b/content/manuals/security/for-admins/single-sign-on/connect.md @@ -50,4 +50,4 @@ The following videos demonstrate how to enforce SSO. ## What's next -Learn how you can [manage your SSO connection](../manage/_index.md), domain, and users for your organization or company. +Learn how you can [manage your SSO connection](../single-sign-on/manage.md), domain, and users for your organization or company. diff --git a/content/manuals/security/for-admins/single-sign-on/manage/_index.md b/content/manuals/security/for-admins/single-sign-on/manage.md similarity index 92% rename from content/manuals/security/for-admins/single-sign-on/manage/_index.md rename to content/manuals/security/for-admins/single-sign-on/manage.md index ae27234d69e1..a9276aa396d9 100644 --- a/content/manuals/security/for-admins/single-sign-on/manage/_index.md +++ b/content/manuals/security/for-admins/single-sign-on/manage.md @@ -71,6 +71,6 @@ aliases: ## What's next? -- [Set up SCIM](../../provisioning/scim.md) -- [Enable Group mapping](../../provisioning/group-mapping.md) +- [Set up SCIM](../provisioning/scim.md) +- [Enable Group mapping](../provisioning/group-mapping.md) diff --git a/content/reference/api/engine/sdk/_index.md b/content/reference/api/engine/sdk/_index.md index 7da7722d9bf5..731b9a6f5553 100644 --- a/content/reference/api/engine/sdk/_index.md +++ b/content/reference/api/engine/sdk/_index.md @@ -84,7 +84,6 @@ import ( "io" "os" - "github.com/docker/docker/api/types" "github.com/docker/docker/api/types/container" "github.com/docker/docker/api/types/image" "github.com/docker/docker/client" @@ -113,7 +112,7 @@ func main() { panic(err) } - if err := cli.ContainerStart(ctx, resp.ID, types.ContainerStartOptions{}); err != nil { + if err := cli.ContainerStart(ctx, resp.ID, container.StartOptions{}); err != nil { panic(err) } @@ -126,7 +125,7 @@ func main() { case <-statusCh: } - out, err := cli.ContainerLogs(ctx, resp.ID, types.ContainerLogsOptions{ShowStdout: true}) + out, err := cli.ContainerLogs(ctx, resp.ID, container.LogsOptions{ShowStdout: true}) if err != nil { panic(err) } diff --git a/content/reference/api/engine/version/v1.47.md b/content/reference/api/engine/version/v1.47.md index ec2eab57f03d..169ce9268487 100644 --- a/content/reference/api/engine/version/v1.47.md +++ b/content/reference/api/engine/version/v1.47.md @@ -3,4 +3,5 @@ linkTitle: v1.47 title: Docker Engine API v1.47 reference aliases: - /reference/api/engine/latest/ + - /engine/api/v1.47/ --- diff --git a/content/subjects/devops/_index.md b/content/subjects/devops/_index.md new file mode 100644 index 000000000000..2d9ad1867487 --- /dev/null +++ b/content/subjects/devops/_index.md @@ -0,0 +1,3 @@ +--- +title: DevOps +--- diff --git a/docker-bake.hcl b/docker-bake.hcl index 8a556ea2aac6..32f915ed24d2 100644 --- a/docker-bake.hcl +++ b/docker-bake.hcl @@ -1,9 +1,9 @@ variable "HUGO_ENV" { - default = "development" + default = null } variable "DOCS_URL" { - default = "https://docs.docker.com" + default = null } variable "DOCS_SITE_DIR" { diff --git a/layouts/guides/landing.html b/layouts/guides/landing.html index 43e62fc69c79..7cd3ba5f9dad 100644 --- a/layouts/guides/landing.html +++ b/layouts/guides/landing.html @@ -154,16 +154,16 @@

{{ .Title }}

{{- define "guide-metadata" }}
-
+
{{- $taxoterms := .GetTerms "languages" }} {{- $taxoterms = $taxoterms | append (.GetTerms "levels") }} {{- $taxoterms = $taxoterms | append (.GetTerms "subjects") }} {{- range $taxoterms }} - {{- .Page.LinkTitle }} + {{- .Page.LinkTitle }} {{- end }}
{{- with .Params.time }} -
+
{{ partialCached "icon" "schedule" "schedule" }} {{ . }}
diff --git a/netlify.toml b/netlify.toml index 05b792caa331..25601ffe5ce3 100644 --- a/netlify.toml +++ b/netlify.toml @@ -4,7 +4,7 @@ publish = "public" [context.deploy-preview.environment] NODE_VERSION = "20" NODE_ENV = "production" -HUGO_VERSION = "0.134.3" +HUGO_VERSION = "0.136.0" HUGO_ENABLEGITINFO = "true" HUGO_ENVIRONMENT = "preview"