-
Notifications
You must be signed in to change notification settings - Fork 8.1k
ENGDOCS-2245 #21059
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
ENGDOCS-2245 #21059
Changes from 10 commits
Commits
Show all changes
12 commits
Select commit
Hold shift + click to select a range
fa5018e
ENGDOCS-2245
aevesdocker 7cf1fcf
module 1 content
aevesdocker b4c1b1d
module 1 content
aevesdocker 20c022c
module 2, 3, 4 content
aevesdocker 1f64ccf
module 2, 3, 4 content
aevesdocker 14895d4
edits and additions
aevesdocker b696174
fix build
aevesdocker 1bc248f
vale stuff
aevesdocker a42343b
more vale fun
aevesdocker 7e3c3fd
change step
aevesdocker b1c5add
docs team review edits
aevesdocker 99e9835
KB review
aevesdocker File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,50 @@ | ||
| --- | ||
| 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. Whether you’re managing Docker Desktop, Docker Hub, or Docker Build Cloud, 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 | ||
|
|
||
| ## 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. | ||
|
|
||
| ## Tools integration | ||
|
|
||
| Okta, Entra ID SAML 2.0, Azure Connect (OIDC), MDM solutions like Intune | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,79 @@ | ||
| --- | ||
| 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 | ||
|
|
||
| ### Baseline configuration | ||
|
|
||
| Through [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md), Docker offers a significant number of configuration parameters that can be preset. | ||
|
|
||
| The Docker organization owner and the development lead should review the settings to determine which of those settings to configure to create the company’s baseline configuration. You should also discuss [enforcing sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) for your Docker Desktop users and whether you want to take advantage of the free trials of other Docker products such as [Docker Scout](/manuals/scout/_index.md), which is included in the subscription. | ||
|
|
||
| {{< accordion title="Baseline settings to review" >}} | ||
aevesdocker marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| | Setting | OS Requirements | Description | | ||
| |---------------------|-----------------|-----------------| | ||
| | `proxy` | | This setting configures the proxy used by Docker Desktop to access the internet. The proxy can be set manually or get its value from the system.| | ||
| | `wslEngineEnabled` | Windows only | This setting specifies whether the user should use WSL 2 or HyperV for the VM for Windows installations.| | ||
| | `kubernetes` | | Docker Desktop offers a Kubernetes single-node cluster for Kubernetes deployments locally. This setting controls whether it is started when Docker Desktop starts, and its configuration.| | ||
| | `analyticsEnabled` | | Docker lets users opt out of sending usage data to Docker. The usage data feeds what admins are able to see about Docker Desktop usage, so it is highly recommended to enable and lock this setting.| | ||
| | `useVirtualizationFrameworkVirtioFS`| macOS only | Virtiofs is the newer higher performance file sharing framework for Mac. It takes precedence over the older frameworks if it is enabled.| | ||
| | `useVirtualizationFrameworkRosetta` | macOS only | Rosetta is the Apple emulator for x86 chipsets. This setting lets Docker Desktop to use Rosetta when running containers built for the x86 chipset.| | ||
| | `allowExperimentalFeatures` | | Docker Desktop versions often contain experimental features for trial and feedback. If this setting is set to false, experimental features are disabled.| | ||
| | `allowBetaFeatures` | | Docker Desktop versions often contain beta features for trial and feedback. If this setting is set to false, beta features are disabled.| | ||
| | `configurationFileVersion` | | Specifies the version of the configuration file format.| | ||
| | `dockerDaemonOptions` - Linux Containers | | This setting overrides the options in the Docker Engine config file. For details, see the [Docker Engine reference](/reference/cli/dockerd.md#daemon-configuration-file). Note that for added security, a few of the config attributes may be overridden when Enhanced Container Isolation is enabled. | | ||
| | `vpnkitCIDR` | | Overrides the network range used for vpnkit DHCP/DNS for `*.docker.internal` | | ||
| | `dockerDaemonOptions` - Windows Containers | Windows only | This setting overrides the options in the daemon config file. For details, see the [Docker Engine reference](/reference/cli/dockerd.md#daemon-configuration-file).| | ||
| | `extensionsEnabled` | | Docker extensions are third-party add-ons for Docker Desktop. This setting affects if they are allowed.| | ||
| | `useGrpcfuse` | macOS only | If the value is set to true, gRPC Fuse is set as the file sharing mechanism. | | ||
| | `displayedOnboarding` | | There is an onboarding survey that displays when Docker Desktop is installed and opened for the first time. This setting can disable the survey.| | ||
|
|
||
| {{< /accordion >}} | ||
|
|
||
| ### Security configuration | ||
|
|
||
| Docker also offers a number of security related features, again through [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md), that can be preset. The infosec representative, Docker organization owner, and the development lead should review those features to determine what should be enabled to meet your company’s security requirements. | ||
|
|
||
| {{< accordion title="Security settings to review" >}} | ||
|
|
||
| | Setting | OS Requirements | Description | | ||
| |------------|-----------------|---------------| | ||
| | Enhanced Container Isolation | | When this setting is enabled, Docker Desktop runs all containers as unprivileged, via the Linux user-namespace, and prevents them from modifying sensitive configurations inside the Docker Desktop VM, and uses other advanced techniques to isolate them. For more information, see [Enhanced Container Isolation](/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/_index.md). | | ||
| | Registry Access Management | | This parameter restricts the registries that `docker pull` and `docker push` commands can access. Note: This is not an endpoint security solution, but a guardrail for users working within company guidelines. For more information, see [Registry Access Management](/manuals/security/for-admins/hardened-desktop/registry-access-management.md).| | ||
| | Image Access Management | | This parameter restricts the categories of images accessible within Docker Hub. Note: This is not an endpoint security solution; it's a guardrail for users working within company guidelines. For more information, see [Image Access Management](/manuals/security/for-admins/hardened-desktop/image-access-management.md).| | ||
| | Scout | | Settings related to how Scout creates SBOMs (Software Bill of Materials) and indexes vulnerabilities for images.| | ||
aevesdocker marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| | `exposeDockerAPIOnTCP2375` | Windows only | Exposes the Docker API on a specified port. If the value is set to true, the Docker API is exposed on port `2375`. This is unauthenticated and should only be enabled if protected by suitable firewall rules.| | ||
| | `windowsDockerdPort` | Windows only | Exposes Docker Desktop's internal proxy locally on this port for the Windows Docker daemon to connect to. It is available for Windows containers only. | | ||
| | `filesharingAllowedDirectories` | | Specify which paths on the developer host machine or network your users can add container file shares to.| | ||
| | `enableKerberosNtlm` | | When set to true, Kerberos and NTLM authentication is enabled. Default is false. Available in Docker Desktop version 4.32 and later.| | ||
| | `containersProxy` | | Lets you create air-gapped containers. For more information, see [Air-Gapped Containers](/manuals/security/for-admins/hardened-desktop/air-gapped-containers.md).| | ||
| | `blockDockerLoad` | | When this setting is enabled, users can no longer run the `docker load` command and will receive an error if they try.| | ||
| | `disableUpdate` | | Users get notifications about new Docker Desktop versions. Enabling this setting removes those notifications. Helpful if corporate IT manages Docker Desktop version updates for users.| | ||
|
|
||
| {{< /accordion >}} | ||
|
|
||
| ## 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 [email protected]. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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).. | ||
aevesdocker marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| > [!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. | ||
aevesdocker marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ## Step three: Begin setup | ||
|
|
||
| ### Set up single sign-on SSO domain verification | ||
|
|
||
| Single sign-on (SSO) lets developers to 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). | ||
aevesdocker marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| You can also enable [SCIM] for further automation of provisioning and deprovisioning of users. | ||
aevesdocker marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| ### 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 supported version of Docker Desktop | ||
aevesdocker marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| > [!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 all users update to a supported version. Docker Desktop versions released within the past 6 months from the latest release are supported. | ||
aevesdocker marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| 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. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should this be a featured guide?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Well it is the first ever admin guide ✨ so perhaps it should be?
@usha-mandya, thoughts?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes. It should be a featured guide. The Docker Compose guide has most views compared to DBC and Scout. So, happy to move one of those to the guides collection.