docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

update Mac FAQs (#9596) 

update Mac FAQs
This commit is contained in:
Usha Mandya 2019-10-25 14:28:35 +01:00 committed by GitHub
parent cc71995855
commit 0823ae8bae
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 75 additions and 219 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

259
docker-for-mac/faqs.md
View File

@ -6,112 +6,42 @@ redirect_from:
title: Frequently asked questions (FAQ)
---
**Looking for popular FAQs on Docker Desktop for Mac?** Check out the
**Looking for popular FAQs on Docker Desktop?** Check out the
[Docker Success Center](http://success.docker.com/){: target="_blank" class="_"}
for knowledge base articles, FAQs, technical support for subscription levels, and more.
## Questions about Docker.app
## Questions about Docker Desktop
### Stable and Edge channels
**Q: How do I get the Stable or Edge version of Docker Desktop for Mac?**
**Q: How do I get the Stable or Edge version of Docker Desktop?**
A: Use the download links for the channels given in the topic
[Download Docker Desktop for Mac](install.md#download-docker-for-mac){: target="_blank" class="_"}.
A: You can download the Stable version of Docker Desktop from [Docker Hub](https://hub.docker.com/?overlay=onboarding). To download the Edge version, see the [Edge release notes](/docker-for-mac/edge-release-notes/).
This topic also has more information about the two channels.
For installation instructions, see [Install Docker Desktop on Mac](install.md){: target="_blank" class="_"}.
**Q: What is the difference between the Stable and Edge versions of Docker Desktop for Mac?**
**Q: What is the difference between the Stable and Edge versions of Docker Desktop?**
A: Two different download channels are available for Docker Desktop for Mac:
A: Two different download channels are available in the Community version of Docker Desktop:
* The **Stable channel** provides a general availability release-ready installer
for a fully baked and tested, more reliable app. The Stable version of Docker
for Mac comes with the latest released version of Docker Engine. The release
schedule is synched with Docker Engine releases and hotfixes. On the Stable
channel, you can select whether to send usage statistics and other data.
The **Stable channel** provides a general availability release-ready installer for a fully baked and tested, more reliable app. The Stable version of Docker Desktop comes with the latest released version of Docker Engine. The release
schedule is synched with Docker Engine releases and patch releases. On the Stable channel, you can select whether to send usage statistics and other data.
* The **Edge channel** provides an installer with new features we are working on,
but is not necessarily fully tested. It comes with the experimental version of
Docker Engine. Bugs, crashes, and issues are more likely to occur with the Edge
app, but you get a chance to preview new functionality, experiment, and provide
feedback as the apps evolve. Releases are typically more frequent than for
Stable, often one or more per month. Usage statistics and crash reports are sent
by default. You do not have the option to disable this on the Edge channel.
The **Edge channel** provides an installer with new features we are working on, but is not necessarily fully tested. It comes with the experimental version of Docker Engine. Bugs, crashes, and issues are more likely to occur with the Edge version, but you get a chance to preview new functionality, experiment, and provide feedback as the apps evolve. Releases are typically more frequent than for Stable, often one or more per month. Usage statistics and crash reports are sent by default. You do not have the option to disable this on the Edge channel.
**Q: Can I switch back and forth between Stable and Edge versions of Docker for Mac?**
**Q: Can I switch between Stable and Edge versions of Docker Desktop?**
A: Yes, you can switch between versions to try out the Edge releases to see what's new,
then go back to Stable for other work. However, **you can have only one app
installed at a time**. Switching back and forth between Stable and Edge apps can
destabilize your development environment, particularly in cases where you switch
from a newer (Edge) channel to older (Stable).
For example, containers created with a newer Edge version of Docker for Mac may
not work after you switch back to Stable because they may have been created
leveraging Edge features that aren't in Stable yet. Just keep this in mind as
you create and work with Edge containers, perhaps in the spirit of a playground
space where you are prepared to troubleshoot or start over.
<font color="#CC3366">To safely switch between Edge and Stable versions be sure
to save images and export the containers you need, then uninstall the current
version before installing another. The workflow is described in more detail
below.</font><br>
#### How to save and restore data
The following procedure can be used to save/restore images and container data,
for example, if you want to switch between Edge and Stable, or reset your VM
disk:
1. Use `docker save -o images.tar image1 [image2 ...]` to save any images you
want to keep. (See [save](/engine/reference/commandline/save) in the Docker
Engine command line reference.)
2. Use `docker export -o myContainner1.tar container1` to export containers you
want to keep. (See [export](/engine/reference/commandline/export) in the
Docker Engine command line reference.)
3. Uninstall the current app & Install a different version of the app (Stable
or Edge), or reset your VM disk.
5. Use `docker load -i images.tar` to reload previously saved images. (See
[load](/engine/reference/commandline/load) in the Docker Engine
6. Use `docker import -i myContainer1.tar` to create a filesystem image
corresponding to previously exported containers. (See
[import](/engine/reference/commandline/import) in the Docker Engine
[This
procedure](https://docs.docker.com/storage/volumes/#backup-restore-or-migrate-data-volumes)
explains how to backup and restore data volumes.
A: Yes, you can switch between Stable and Edge versions. You can try out the Edge releases to see what's new, then go back to Stable for other work. However, **you can only have one version of Docker Desktop installed at a time**. For more information, see [Switch between Stable and Edge versions](/docker-for-mac/install/#switch-between-stable-and-edge-versions).
### What is Docker.app?
`Docker.app` is Docker for Mac, a bundle of Docker client, and Docker Engine.
`Docker.app` uses the macOS Hypervisor.framework to run containers, meaning that
no separate VirtualBox is required.
`Docker.app` is Docker Desktop on Mac. It bundles the Docker client and Docker Engine. `Docker.app` uses the macOS Hypervisor.framework to run containers, which means that a separate VirtualBox is not required to run Docker Desktop.
### What are system requirements for Docker for Mac?
### What are the system requirements for Docker Desktop?
You need a Mac that supports hardware virtualization. For more information, see [Docker Desktop Mac system requirements](install/#system-requirements).
### Do I need to reinstall Docker for Mac if I change the name of my macOS account?
Starting with Docker for Mac Edge 18.06, this path is relative to the user's
home directory, so it should never be a problem. The remainder of this section
is about older releases of Docker for Mac.
If, after installing Docker for Mac, you [change the name of your macOS user
account and home folder](https://support.apple.com/en-us/HT201548), Docker for
Mac fails to start. [Reset to Factory Defaults](/docker-for-mac/index/#reset) is the simplest
fix, but you'll lose all your settings, containers, images, etc.
To preserve them, open the `~/Library/Group
Containers/group.com.docker/settings.json` file, and update the `diskPath`
entry.
### Do I need to uninstall Docker Toolbox to use Docker for Mac?
### Do I need to uninstall Docker Toolbox to use Docker Desktop?
No, you can use these side by side. Docker Toolbox leverages a Docker daemon
installed using `docker-machine` in a machine called `default`. Running `eval
@ -123,18 +53,15 @@ To make the client talk to the Docker for Mac Engine, run the command `unset
${!DOCKER_*}` to unset all DOCKER environment variables in the current shell.
(Now, `env | grep DOCKER` should return no output.) You can have multiple
command line shells open, some set to talk to Engine from Toolbox and others set
to talk to Docker for Mac. The same applies to `docker-compose`.
to talk to Docker Desktop. The same applies to `docker-compose`.
### How do I uninstall Docker Toolbox?
You might decide that you do not need Toolbox now that you have Docker for Mac,
and want to uninstall it. For details on how to perform a clean uninstall of
Toolbox on the Mac, see [How to uninstall Toolbox](/toolbox/toolbox_install_mac/#how-to-uninstall-toolbox)
in the Toolbox Mac topics.
Now that you have installed Docker Desktop, you might decide that you do not need the legacy Docker Toolbox anymore. For details on how to perform a clean uninstall of Toolbox on Mac, see [How to uninstall Toolbox](/toolbox/toolbox_install_mac/#how-to-uninstall-toolbox).
## Experimental features
{% include experimental-feature.md %}
{% include experimental.md %}
## Questions about feedback and help
@ -145,30 +72,23 @@ process, startup, functionality available, the GUI, usefulness of the app,
command line integration, and so on. Tell us about problems, what you like, or
functionality you'd like to see added.
We are especially interested in getting feedback on the new swarm mode described
in [Docker Swarm](/engine/swarm/index.md). A good place to start is the
[tutorial](/engine/swarm/swarm-tutorial/index.md).
### What if I have problems or questions?
You can find the list of frequent issues in
[Logs and Troubleshooting](troubleshoot.md).
You can find the list of frequent issues in [Logs and Troubleshooting](troubleshoot.md).
If you do not find a solution in Troubleshooting, browse issues on
[Docker for Mac issues on GitHub](https://github.com/docker/for-mac/issues){: target="_blank" class="_"} or
create a new one. You can also create new issues based on diagnostics. To learn more,
see
[Docker Desktop for Mac issues on GitHub](https://github.com/docker/for-mac/issues){: target="_blank" class="_"} or create a new one. You can also create new issues based on diagnostics. To learn more, see
[Diagnose problems, send feedback, and create GitHub issues](troubleshoot.md#diagnose-problems-send-feedback-and-create-github-issues).
[Docker for Mac forum](https://forums.docker.com/c/docker-for-mac){: target="_blank" class="_"}
[Docker Desktop for Mac forum](https://forums.docker.com/c/docker-for-mac){: target="_blank" class="_"}
provides discussion threads as well, and you can create discussion topics there,
but we recommend using the GitHub issues over the forums for better tracking and
response.
### How can I opt out of sending my usage data?
If you do not want auto-send of usage data, use the Stable channel. For more
information, see [Stable and Edge channels](#stable-and-edge-channels) ("What is the difference between the Stable and Edge versions of Docker for Mac?").
If you do not want to send of usage data, use the Stable channel. For more
information, see _What is the difference between the Stable and Edge versions of Docker Desktop?_ in [Stable and Edge channels](#stable-and-edge-channels).
### How is personal data handled in Docker Desktop?
@ -188,25 +108,16 @@ diagnostics bundle to investigate specific user issues, but may derive high
level (non personal) metrics such as the rate of issues from it.
## How can I...?
### Can I use Docker for Mac with swarm mode?
Yes, you can use Docker for Mac to test single-node features of [swarm
mode](/engine/swarm/index.md) introduced with Docker Engine 1.12, including
initializing a swarm with a single node, creating services, and scaling
services. Docker “Moby” on Hyperkit serves as the single swarm node. You can
also use Docker Machine, which comes with Docker for Mac, to create and
experiment a multi-node swarm. Check out the tutorial at [Get started with swarm
mode](/engine/swarm/swarm-tutorial/index.md).
### How do I connect to the remote Docker Engine API?
You might need to provide the location of the Engine API for Docker clients and
development tools.
On Docker for Mac, clients can connect to the Docker Engine through a Unix
On Docker Desktop, clients can connect to the Docker Engine through a Unix
socket: `unix:///var/run/docker.sock`.
See also [Docker Engine API](/engine/api.md) and Docker for Mac forums topic
See also [Docker Engine API](/engine/api.md) and Docker Desktop for Mac forums topic
[Using pycharm Docker plugin..](https://forums.docker.com/t/using-pycharm-docker-plugin-with-docker-beta/8617){: target="_blank" class="_"}.
If you are working with applications like [Apache Maven](https://maven.apache.org/){: target="_blank" class="_"}
@ -220,130 +131,40 @@ export DOCKER_HOST=unix:///var/run/docker.sock
### How do I connect from a container to a service on the host?
The Mac has a changing IP address (or none if you have no network access). Our
current recommendation is to attach an unused IP to the `lo0` interface on the
Mac has a changing IP address (or none if you have no network access). We recommend that you attach an unused IP to the `lo0` interface on the
Mac so that containers can connect to this address.
For a full explanation and examples, see
[I want to connect from a container to a service on the host](networking.md#i-want-to-connect-from-a-container-to-a-service-on-the-host)
under
[Known Limitations, Use Cases, and Workarounds](networking.md#known-limitations-use-cases-and-workarounds)
in the Networking topic.
For more information and examples, see
[I want to connect from a container to a service on the host](networking.md#i-want-to-connect-from-a-container-to-a-service-on-the-host) in the [Networking](/docker-for-mac/networking/) topic.
### How do I connect to a container from the Mac?
### How do I connect to a container from Mac?
Our current recommendation is to publish a port, or to connect from another
container. This is what you need to do even on Linux if the container
is on an overlay network, not a bridge network, as these are not routed.
We recommend that you publish a port, or connect from another container. You can use the same method on Linux if the container is on an overlay network and not a bridge network, as these are not routed.
For a full explanation and examples, see
[I want to connect to a container from the Mac](networking.md#i-want-to-connect-to-a-container-from-the-mac)
under
[Known Limitations, Use Cases, and Workarounds](networking.md#known-limitations-use-cases-and-workarounds)
in the Networking topic.
For more information and examples, see
[I want to connect to a container from the Mac](networking.md#i-want-to-connect-to-a-container-from-the-mac) in the [Networking](/docker-for-mac/networking/) topic.
### How do I add custom CA certificates?
Starting with Docker for Mac Beta 27 and Stable 1.12.3, all trusted certificate
authorities (CAs) (root or intermediate) are supported.
For full information on adding server and client side certs, see
Docker Desktop supports all trusted certificate authorities (CAs) (root or intermediate). For more information on adding server and client side certs, see
[Add TLS certificates](/docker-for-mac/index/#add-tls-certificates) in the Getting Started topic.
### How do I add client certificates?
Starting with Docker for Mac 17.06.0-ce, you do not need to push your
certificates with `git` commands anymore. You can put your client certificates
in `~/.docker/certs.d/<MyRegistry>:<Port>/client.cert` and
`~/.docker/certs.d/<MyRegistry>:<Port>/client.key`.
For full information on adding server and client side certs, see
[Add TLS certificates](/docker-for-mac/index/#add-tls-certificates) in the Getting Started topic.
For information on adding client certificates, see
[Add client certificates](/docker-for-mac/index/#add-client-certificates) in the Getting Started topic.
### Can I pass through a USB device to a container?
Unfortunately it is not possible to pass through a USB device (or a
serial port) to a container. For use cases requiring this, we
recommend the use of [Docker Toolbox](/toolbox/overview.md).
Unfortunately, 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.
## Disk Usage
### Can I run Docker Desktop in nested virtualization scenarios?
### What is the disk image?
Docker Desktop can run inside a Windows 10 VM running on apps like Parallels or VMware Fusion on a Mac provided that the VM is properly configured. However, problems and intermittent failures may still occur due to the way these apps virtualize the hardware. For these reasons, **Docker Desktop is not supported in nested virtualization scenarios**. It might work in some cases, and not in others. For more information, see [Running Docker Desktop in nested virtualization scenarios](/docker-for-windows/troubleshoot/#running-docker-desktop-in-nested-virtualization-scenarios).
The containers and images are stored in a _disk image_ named `Docker.raw` or
`Docker.qcow2` depending on your settings (see below). By default, the disk
image is stored in `~/Library/Containers/com.docker.docker/Data/vms/0`.
## Components of Docker Desktop
### Qcow2 or Raw?
Starting with High Sierra with Apple Filesystem (APFS) enabled, Docker
uses disk images in the "raw" format (`Docker.raw`), otherwise in the
Qcow2 format (`Docker.qcow2`).
### Docker.raw consumes an insane amount of disk space!
This is an illusion. Docker uses the raw format on Macs running the Apple
Filesystem (APFS). APFS supports _sparse files_, which compress long runs of
zeroes representing unused space. The output of `ls` is misleading, because it
lists the logical size of the file rather than its physical size. To see the
physical size, add the `-ks` switch; to see the logical size in human readable
form, add `-lh`:
```bash
$ cd ~/Library/Containers/com.docker.docker/Data/vms/0
$ ls -klsh Docker.raw
2333548 -rw-r--r--@ 1 akim staff 64G Dec 13 17:42 Docker.raw
```
In this listing, the logical size is 64GB, but the physical size is
only 2.3GB.
Alternatively, you may use `du` (disk usage):
```bash
$ du -h Docker.raw
2,2G Docker.raw
```
### How do I reduce the size of Docker.qcow2?
If your Docker for Mac uses the Qcow format, the [disk image
file](#what-is-the-disk-image) is `Docker.qcow2`. This file grows
on-demand up to a default maximum file size of 64GiB.
In Docker 1.12 the only way to free space on the host is to delete
this file and restart the app. Unfortunately this removes all images
and containers.
In Docker 1.13 there is preliminary support for "TRIM" to non-destructively
free space on the host. First free space within the `Docker.qcow2` by
removing unneeded containers and images with the following commands:
- `docker ps -a`: list all containers
- `docker image ls`: list all images
- `docker system prune`: (new in 1.13): deletes all stopped containers, all
volumes not used by at least one container, and all images without at least one
referring container.
Note the `Docker.qcow2` does not shrink in size immediately.
In 1.13 a background `cron` job runs `fstrim` every 15 minutes.
If the space needs to be reclaimed sooner, run this command:
```bash
$ docker run --rm -it --privileged --pid=host walkerlee/nsenter -t 1 -m -u -i -n fstrim /var
```
Once the `fstrim` has completed, restart the app. When the app shuts down, it
compacts the file and free up space. The app
takes longer than usual to restart because it must wait for the
compaction to complete.
For background conversation thread on this, see
[Docker.qcow2 never shrinks...](https://github.com/docker/for-mac/issues/371)
on Docker for Mac GitHub issues.
## Components of Docker for Mac
### What is HyperKit?
HyperKit is a hypervisor built on top of the Hypervisor.framework in macOS. It runs entirely in userspace and has no other

35
docker-for-mac/install.md
View File

@ -78,6 +78,41 @@ The Docker Desktop installation includes
Congratulations! You are now successfully running Docker Desktop.
## Switch between Stable and Edge versions
Docker Desktop allows you to switch between Stable and Edge releases. However, **you can only have one version of Docker Desktop installed at a time**. Switching between Stable and Edge versions can destabilize your development environment, particularly in cases where you switch from a newer (Edge) channel to an older (Stable) channel.
For example, containers created with a newer Edge version of Docker Desktop may
not work after you switch back to Stable because they may have been created
using Edge features that aren't in Stable yet. Keep this in mind as
you create and work with Edge containers, perhaps in the spirit of a playground
space where you are prepared to troubleshoot or start over.
To safely switch between Edge and Stable versions, ensure you save images and export the containers you need, then uninstall the current version before installing another. For more information, see the section Save and Restore data below.
### Save and restore data
You can use the following procedure to save and restore images and container data. For example, if you want to switch between Edge and Stable, or to reset your VM disk:
1. Use `docker save -o images.tar image1 [image2 ...]` to save any images you
want to keep. See [save](/engine/reference/commandline/save) in the Docker
Engine command line reference.
2. Use `docker export -o myContainner1.tar container1` to export containers you
want to keep. See [export](/engine/reference/commandline/export) in the
Docker Engine command line reference.
3. Uninstall the current version of Docker Desktop and install a different version (Stable or Edge), or reset your VM disk.
4. Use `docker load -i images.tar` to reload previously saved images. See
[load](/engine/reference/commandline/load) in the Docker Engine.
5. Use `docker import -i myContainer1.tar` to create a filesystem image
corresponding to the previously exported containers. See
[import](/engine/reference/commandline/import) in the Docker Engine.
For information on how to back up and restore data volumes, see [Backup, restore, or migrate data volumes](/storage/volumes/#backup-restore-or-migrate-data-volumes).
## Where to go next
- [Getting started](index.md) provides an overview of Docker Desktop on Mac, basic Docker command examples, how to get help or give feedback, and links to other topics about Docker Desktop on Mac.