Legacy desktop solution. Docker Toolbox is for older Mac and Windows systems that do not meet the requirements of Docker Desktop for Mac and Docker Desktop for Windows. We recommend updating to the newer applications, if possible.
Estimated reading time: 9 minutes Docker has enabled developers to use containers when working on any application -whether is a new microservice or an existing application. Containers package up the code, configs and dependencies into an isolated bundle, potentially making the application more secure and portable.
Docker Toolbox provides a way to use Docker on older Macsthat do not meetminimal system requirements for Docker Desktop for Mac.
What you get and how it works
Docker Toolbox includes the following Docker tools:
- Docker CLI client for running Docker Engine to create images and containers
- Docker Machine so you can run Docker Engine commands from macOS terminals
- Docker Compose for running the
docker-compose
command - Kitematic, the Docker GUI
- the Docker QuickStart shell preconfigured for a Docker command-line environment
- Oracle VM VirtualBox
Because the Docker Engine daemon uses Linux-specifickernel features, you can’t run Docker Engine natively onmacOS with Docker Toolbox. Instead, you must use theDocker Machine command,
docker-machine
, to create andattach to a small Linux VM on your machine. This VM hostsDocker Engine for you on your Mac.Tip: One of the advantages of the newerDocker Desktop for Mac solution is thatit uses native virtualization and does not requireVirtualBox to run Docker.
Step 1: Check your version
Your Mac must be running macOS 10.8 “Mountain Lion” or newer to run Dockersoftware. To find out what version of the OS you have:
- Choose About this Mac from the Apple menu.The version number appears directly below the words
macOS
. - If you have the correct version, go to the next step.If you aren’t using a supported version, you could consider upgrading your operating system.If you have macOS 10.10.3 Yosemite or newer, consider using Docker Desktop for Mac instead. It runs natively on the Mac, so there is no need for a pre-configured Docker QuickStart shell. It uses the native macOS Hypervisor framework for virtualization, instead of Oracle VirutalBox. Full install prerequisites are provided in the Docker Desktop for Mac topic in Docker Desktop for Mac.
Step 2: Install Docker Toolbox
Note: Docker are no longer maintaining the download.docker.com url forDocker Toolbox, therefore an unsigned warning (verified publisher dialog) isdisplayed during the installation process.
- To download the latest version of Docker Toolbox, go to ToolboxReleases and download thelatest
.pkg
file. - Install Docker Toolbox by double-clicking the package or by right-clickingand choosing “Open” from the pop-up menu.The installer launches an introductory dialog, followed by an overview of what’s installed.
- Press Continue to install the toolbox.The installer presents you with options to customize the standard installation.By default, the standard Docker Toolbox installation:
- installs binaries for the Docker tools in
/usr/local/bin
- makes these binaries available to all users
- updates any existing Virtual Box installation
For now, don’t change any of the defaults. - installs binaries for the Docker tools in
- Press Install to perform the standard installation.The system prompts you for your password.
- Provide your password to continue with the installation.When it completes, the installer provides you with some shortcuts. You can ignore this for now and click Continue.Then click Close to finish the installer.
Step 3: Verify your installation
To run a Docker container, you:
- create a new (or start an existing) Docker Engine host running
- switch your environment to your new VM
- use the
docker
client to create, load, and manage containers
Once you create a machine, you can reuse it as often as you like. Like anyVirtual Box VM, it maintains its configuration between uses.
- Open the Launchpad and locate the Docker Quickstart Terminal icon.
- Click the icon to launch a Docker Quickstart Terminal window.The terminal does a number of things to set up Docker Quickstart Terminal for you.
- Click your mouse in the terminal window to make it active.If you aren’t familiar with a terminal window, here are some quick tips.The prompt is traditionally a
$
dollar sign. You type commands into thecommand line which is the area after the prompt. Your cursor is indicatedby a highlighted area or a|
that appears in the command line. Aftertyping a command, always press RETURN. - Type the
docker run hello-world
command and press RETURN.The command does some work for you, if everything runs well, the command’s output looks like this:
Optional: Add shared directories
By default, Toolbox only has access to the
/Users
directory and mounts it intothe VMs at /Users
. If your project lives elsewhere or needs access to otherdirectories on the host filesystem, you can add them.Use the VirtualBox GUI
You can configure shared folders in the VirtualBox UI.
- Open the VirtualBox UI.
- Click the Settings gear, then go to Shared Folders.
- Select any existing listing under Machine Folders, thenclick the + icon.
- Choose the Folder Path on the host, enter the Folder Namefor within the VM (or take the default, which is the same nameas on the host), and configure any additional options you need.
- Choose Auto-mount if you want the folder to automaticallybe mounted into the VM, and choose Make Permanent for itto be considered a permanently shared folder.
- Click OK to add the new folder to the Shared Folders list.
- Click OK again to save your changes and exit the Settings dialog.
Use the command line
You can configure shared folders using a command like the following:
This command mounts
/some/mount/location
into the VM at /your-other-share-hame
,owned by UID 1000 and GID 50.Note: The autommount and permanent mount options are not supported usingthe command line.
How to uninstall Toolbox
Removing Toolbox involves removing all the Docker components it includes.
A full uninstall also includes removing the local and remote machinesyou created with Docker Machine. In some cases, you might want to keepmachines created with Docker Machine.
For example, if you plan to re-install Docker Machine as a part ofDocker Desktop for Mac you can continue to manage those machines throughDocker. Or, if you have remote machines on a cloud provider and youplan to manage them using the provider, you wouldn’t want to removethem. So the step to remove machines is described here as optional.
To uninstall Toolbox on a Mac, do the following:
- List your machines.
- Optionally, remove each machine. For example:This step is optional because if you planto re-install Docker Machine as a partof Docker Desktop for Mac, you can import andcontinue to manage those machines through Docker.
- In your “Applications” folder, remove the “Docker” directory,which contains “Docker Quickstart Terminal” and “Kitematic”.
- Run the following in a command shell to fully remove Kitematic:
- Remove the
docker
,docker-compose
, anddocker-machine
commands fromthe/usr/local/bin
folder. Docker Desktop for Mac and Brew may also haveinstalled them; in case of doubt leave them, or reinstall them via Brew, orrerun Docker Desktop for Mac (no need to reinstall it). - Optionally, remove the
~/.docker/machine
directory.This directory stores some configuration and/or state, such as informationabout created machines and certificates. - Uninstall Oracle VirtualBox, which is installed as a part of theToolbox install.
Next steps
- Try the Get started tutorial.
- Dig in deeper with more tutorials and examples on building images, running containers, networking, managing data, and storing images on Docker Hub.
Configure Containers
Install docker toolbox
Follow instructions https://docs.docker.com/toolbox/toolbox_install_windows/
Change default vm settings
The default Virtual Box VM does not provide enough resources to give a good experience when building Yocto images. We recommend you create a new VM with at least 2 CPUs and 4GB of memory.
- Run Docker Quickstart Terminal and then run the following commands in that terminal.
- Remove the default vm
- Re-create the default vm
- Choose the number of cpus with --virtualbox-cpu-count. For this example we'll use two.
- Choose the amount of RAM: --virtualbox-memory. This is also based on the host hardware. However, choose at least 4GB.
- Choose the amount of disk space: --virtualbox-disk-size. It is recommended that this be at least 50GB since building generates a lot* of output. In this example we'll choose 50GB.
- Create vm with new settings
- Restart docker
Then start open a new Docker Quickstart Terminal.
Create the samba container
- In the new quickstart terminal create a volume as follows.
- Create a samba container that will allow you to see the files in the volume.
- Start the samba container
- Get the ip address used to talk to samba and open /workdirThe result of this command is the address you will use to see the workdir.In this example let's say the command returned 192.168.99.100. Now, to seethe workdir open the file browser in windows (win+e) and type
Using the poky container
Before using the poky container, make sure the samba container is running. Note that if you have started it in a previous terminal it will still be running. Run poky container as follows, note that we use the volume created above when specifying the workdir.
You will see a prompt that looks like
pokyuser@892e5d2574d6:/workdir$
Although this is called the poky container, it does not include the bitbake meta-data for the Yocto Project poky distro, instead it is a Linux environment with all dependencies already installed. See the Yocto Project Development Tasks Manual to get started with with Yocto project.
Troubleshooting
Cannot connect to docker
You may see the following error when starting the QuickStart terminal
First look in at Network Adapters section in Device Manager. If you see entries named 'Virtual Box Bridged Network Driver' wit ha yellow bang against them, you should remove them. Typically simply uninstalling does not work do you must do the following instead
- Select driver entry
- Right click on it and select 'Update Driver Sofware'
- In resulting window, click on 'Browse my computer....'
- Then click on 'Let me pick'
- Selected chosen driver and click on 'Next'
If that does not fix the problem, start Oracle VirtualBox and remove host-only networks
- File -> Preferences -> Network -> Host only Network
- Select each network and hit '-' button