diff --git a/toolbox/faqs/index.md b/toolbox/faqs/index.md deleted file mode 100644 index 434ae6bcdb..0000000000 --- a/toolbox/faqs/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -advisory: toolbox -description: FAQs, troubleshooting, and tips index for Toolbox installs -identifier: toolbox_overview_faqs -keywords: docker, documentation, about, technology, kitematic, gui, toolbox -title: FAQs and troubleshooting ---- - -This is a frequently asked questions (FAQs) and troubleshooting guide for non-technical users who are learning about Docker, starting with [Docker Toolbox](https://www.docker.com/products/docker-toolbox). - -By following the getting started, you'll learn fundamental Docker features by performing some simple tasks. - -In the process of installing and setting up Docker, you might run into problems or have questions about configuration and setup. - -* _**Looking for help with error messages?**_ Go to [Troubleshooting](troubleshoot.md). - -  diff --git a/toolbox/faqs/troubleshoot.md b/toolbox/faqs/troubleshoot.md deleted file mode 100644 index 725a9c7bba..0000000000 --- a/toolbox/faqs/troubleshoot.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -advisory: toolbox -description: Troubleshooting connectivity and certificate issues -keywords: beginner, getting started, FAQs, troubleshooting, Docker -title: Troubleshooting ---- - -Typically, the QuickStart works out-of-the-box, but some scenarios can cause problems. - -## Example errors - -You might get errors when attempting to connect to a machine (such as with `docker-machine env default`) or pull an image from Docker Hub (as with `docker run hello-world`). - -The errors you get might be specific to certificates, like this: - - Error checking TLS connection: Error checking and/or regenerating the certs: There was an error validating certificates for host "192.168.99.100:2376": dial tcp 192.168.99.100:2376: i/o timeout - -Others explicitly suggest regenerating certificates: - - Error checking TLS connection: Error checking and/or regenerating the certs: There was an error validating certificates for host "192.168.99.100:2376": x509: certificate is valid for 192.168.99.101, not 192.168.99.100 - You can attempt to regenerate them using 'docker-machine regenerate-certs [name]'. - Be advised that this will trigger a Docker daemon restart which will stop running containers. - -Or, indicate a network timeout, like this: - - bash-3.2$ docker run hello-world - Unable to find image 'hello-world:latest' locally - Pulling repository docker.io/library/hello-world - Network timed out while trying to connect to https://index.docker.io/v1/repositories/library/hello-world/images. You may want to check your internet connection or if you are behind a proxy. - bash-3.2$ - -## Solutions - -Here are some quick solutions to help get back on track. These examples assume the Docker host is a machine called `default`. - -#### Regenerate certificates - -Some errors explicitly tell you to regenerate certificates. You might also try this for other errors that are certificate and/or connectivity related. - - $ docker-machine regenerate-certs default - Regenerate TLS machine certs? Warning: this is irreversible. (y/n): y - Regenerating TLS certificates - -#### Restart the Docker host - - $ docker-machine restart default - -After the machine starts, set the environment variables for the command window. - - $ eval $(docker-machine env default) - -Run `docker-machine ls` to verify that the machine is running and that this command window is configured to talk to it, as indicated by an asterisk for the active machine (__*__). - - $ docker-machine ls - NAME ACTIVE DRIVER STATE URL SWARM DOCKER ERRORS - default * virtualbox Running tcp://192.168.99.101:2376 v1.10.1 - -#### Stop the machine, remove it, and create a new one. - - $ docker-machine stop default - Stopping "default"... - Machine "default" was stopped. - - $ docker-machine rm default - About to remove default - Are you sure? (y/n): y - Successfully removed default - -You can use the `docker-machine create` command with the `virtualbox` driver to create a new machine called `default` (or any name you want for the machine). - - $ docker-machine create --driver virtualbox default - Running pre-create checks... - (default) Default Boot2Docker ISO is out-of-date, downloading the latest release... - (default) Latest release for github.com/boot2docker/boot2docker is v1.10.1 - (default) Downloading - ... - Docker is up and running! - To see how to connect your Docker Client to the Docker Engine running on this virtual machine, run: docker-machine env default - -Set the environment variables for the command window. - - $ eval $(docker-machine env default) - -Run `docker-machine ls` to verify that the new machine is running and that this command window is configured to talk to it, as indicated by an asterisk for the active machine (__*__). - - - -## HTTP proxies and connectivity errors - -A special brand of connectivity errors can be caused by HTTP proxy. If you install Docker Toolbox on a system using a virtual private network (VPN) that uses an HTTP proxy (such as a corporate network), you might encounter errors when the client attempts to connect to the server. - -Here are examples of this type of error: - - $ docker run hello-world - An error occurred trying to connect: Post https://192.168.99.100:2376/v1.20/containers/create: Forbidden - - $ docker run ubuntu echo "hi" - An error occurred trying to connect: Post https://192.168.99.100:2376/v1.20/containers/create: Forbidden - -### Configure HTTP proxy settings on Docker machines - -When Toolbox creates virtual machines (VMs) it runs `start.sh`, where it gets values for `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`, and passes them as `create` options to create the `default machine`. - -You can reconfigure HTTP proxy settings for private networks on already-created Docker machines, such as the `default` machine, then change the configuration when you are using the same system on a different network. - -Alternatively, you can modify proxy settings on your machine(s) manually through the configuration file at `/var/lib/boot2docker/profile` inside the VM, or configure proxy settings as a part of a `docker-machine create` command. - -Both solutions are described below. - -#### Update /var/lib/boot2docker/profile on the Docker machine - -One way to solve this problem is to update the file `/var/lib/boot2docker/profile` on an existing machine to specify the proxy settings you want. - -This file lives on the VM itself, so you need to `ssh` into the machine, then edit and save the file there. - -You can add your machine addresses as values for a `NO_PROXY` setting, and also specify proxy servers that you know about and you want to use. Typically setting your Docker machine URLs to `NO_PROXY` solves this type of connectivity problem, so that example is shown here. - -1. Use `ssh` to log in to the virtual machine. This example logs in to the - `default` machine. - - $ docker-machine ssh default - docker@default:~$ sudo vi /var/lib/boot2docker/profile - -2. Add a `NO_PROXY` setting to the end of the file similar to the example below. - - # replace with your office's proxy environment - export "HTTP_PROXY=http://PROXY:PORT" - export "HTTPS_PROXY=http://PROXY:PORT" - # you can add more no_proxy with your environment. - export "NO_PROXY=192.168.99.*,*.local,169.254/16,*.example.com,192.168.59.*" - -3. Restart Docker. - - After you modify the `profile` on your VM, restart Docker and log out of the machine. - - docker@default:~$ sudo /etc/init.d/docker restart - docker@default:~$ exit - - Re-try Docker commands. Both Docker and Kitematic should run properly now. - - When you move to a different network (for example, leave the office's corporate network and return home), remove or comment out these proxy settings in `/var/lib/boot2docker/profile` and restart Docker. - -#### Create machines manually using --engine env to specify proxy settings - -Rather than reconfigure automatically-created machines, you can delete them and create your `default` machine and others manually with the `docker-machine create` command, using the `--engine env` flag to specify the proxy settings you want. - -Here is an example of creating a `default` machine with proxies set to `http://example.com:8080` and `https://example.com:8080`, and a `N0_PROXY` setting for the server `example2.com`. - - docker-machine create -d virtualbox \ - --engine-env HTTP_PROXY=http://example.com:8080 \ - --engine-env HTTPS_PROXY=https://example.com:8080 \ - --engine-env NO_PROXY=example2.com \ - default - - -To learn more about using `docker-machine create`, see the [create](../../machine/reference/create.md) command in the [Docker Machine](../../machine/overview.md) reference. - -  diff --git a/toolbox/images/applications_folder.png b/toolbox/images/applications_folder.png deleted file mode 100644 index 53cdb9dbbf..0000000000 Binary files a/toolbox/images/applications_folder.png and /dev/null differ diff --git a/toolbox/images/b2d_shell.png b/toolbox/images/b2d_shell.png deleted file mode 100644 index 2d17cd08b0..0000000000 Binary files a/toolbox/images/b2d_shell.png and /dev/null differ diff --git a/toolbox/images/finish.png b/toolbox/images/finish.png deleted file mode 100644 index 4ab90493fd..0000000000 Binary files a/toolbox/images/finish.png and /dev/null differ diff --git a/toolbox/images/icon-set.png b/toolbox/images/icon-set.png deleted file mode 100644 index d2c4b68337..0000000000 Binary files a/toolbox/images/icon-set.png and /dev/null differ diff --git a/toolbox/images/installer_open.png b/toolbox/images/installer_open.png deleted file mode 100644 index 33c21ca504..0000000000 Binary files a/toolbox/images/installer_open.png and /dev/null differ diff --git a/toolbox/images/mac-page-finished.png b/toolbox/images/mac-page-finished.png deleted file mode 100644 index 4075f6e07a..0000000000 Binary files a/toolbox/images/mac-page-finished.png and /dev/null differ diff --git a/toolbox/images/mac-page-quickstart.png b/toolbox/images/mac-page-quickstart.png deleted file mode 100644 index 26e41a5c03..0000000000 Binary files a/toolbox/images/mac-page-quickstart.png and /dev/null differ diff --git a/toolbox/images/mac-page-two.png b/toolbox/images/mac-page-two.png deleted file mode 100644 index 86c9ed293e..0000000000 Binary files a/toolbox/images/mac-page-two.png and /dev/null differ diff --git a/toolbox/images/mac-password-prompt.png b/toolbox/images/mac-password-prompt.png deleted file mode 100644 index a6f8d86f47..0000000000 Binary files a/toolbox/images/mac-password-prompt.png and /dev/null differ diff --git a/toolbox/images/mac-welcome-page.png b/toolbox/images/mac-welcome-page.png deleted file mode 100644 index 4bc9fd633b..0000000000 Binary files a/toolbox/images/mac-welcome-page.png and /dev/null differ diff --git a/toolbox/images/terminal.png b/toolbox/images/terminal.png deleted file mode 100644 index 8b6b2cc37d..0000000000 Binary files a/toolbox/images/terminal.png and /dev/null differ diff --git a/toolbox/images/toolbox-installer.png b/toolbox/images/toolbox-installer.png deleted file mode 100644 index 6667dc19b5..0000000000 Binary files a/toolbox/images/toolbox-installer.png and /dev/null differ diff --git a/toolbox/images/virtualization.png b/toolbox/images/virtualization.png deleted file mode 100644 index 50a0a90044..0000000000 Binary files a/toolbox/images/virtualization.png and /dev/null differ diff --git a/toolbox/index.md b/toolbox/index.md deleted file mode 100644 index f4029f366c..0000000000 --- a/toolbox/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -advisory: toolbox -description: Documentation that provides an overview of Docker Toolbox and installation instructions -keywords: docker, documentation, about, technology, docker toolbox, gui -title: Docker Toolbox ---- - -**Note** while Docker Toolbox is now considered Legacy, Kitematic is still supported and available as a separate download from [https://github.com/docker/kitematic](https://github.com/docker/kitematic) - -Available for both Windows and Mac, Docker Toolbox installs the Docker Client, Machine, Compose, and Kitematic. - -**Learn about Docker Toolbox**. See [Docker Toolbox Overview](overview.md) for a quick tour of Toolbox, and -how to get started with Docker Machine, Kitematic, and Docker Compose. - -**Ready to download Toolbox?** See [Install Docker Toolbox on macOS](toolbox_install_mac.md) or [Install Docker Toolbox on Windows](toolbox_install_windows.md) for download and install instructions. diff --git a/toolbox/overview.md b/toolbox/overview.md deleted file mode 100644 index b652c03c3c..0000000000 --- a/toolbox/overview.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -advisory: toolbox -description: Documentation that provides an overview of Toolbox -keywords: docker, documentation, about, technology, kitematic, gui, toolbox -title: Docker Toolbox overview ---- - -Docker Toolbox is an installer for quick setup and launch of a Docker environment on older Mac and Windows systems that do not meet the requirements of the new [Docker Desktop for Mac](../docker-for-mac/index.md) and [Docker Desktop for Windows](../docker-for-windows/index.md) apps. - -![Toolbox installer](images/toolbox-installer.png) - -## What's in the box - -Toolbox includes these Docker tools: - -* Docker Machine for running `docker-machine` commands - -* Docker Engine for running the `docker` commands - -* Docker Compose for running the `docker-compose` commands - -* Kitematic, the Docker GUI - -* a shell preconfigured for a Docker command-line environment - -* Oracle VirtualBox - -You can find various versions of the tools on [Toolbox Releases](https://github.com/docker/toolbox/releases) or run them with the `--version` flag in the terminal, for example, `docker-compose --version`. - - -## Ready to get started? - -Choose the install instructions for your platform, and follow the steps: - - - [Install Docker Toolbox for macOS](toolbox_install_mac.md) - - - [Install Docker Toolbox for Windows](toolbox_install_windows.md) - -## Next steps - -* Try the [Get started](../get-started/index.md) tutorial. - -* Dig in deeper with [more tutorials and examples](../engine/tutorials/index.md) on building images, running containers, networking, managing data, and storing images on Docker Hub. - -* [Learn about Kitematic](../kitematic/userguide.md) - -* [Learn about Docker Machine](../machine/overview.md) - -* [Learn about Docker Compose](../compose/index.md) diff --git a/toolbox/toolbox_install_mac.md b/toolbox/toolbox_install_mac.md deleted file mode 100644 index 3927ea8564..0000000000 --- a/toolbox/toolbox_install_mac.md +++ /dev/null @@ -1,319 +0,0 @@ ---- -advisory: toolbox -description: How to install Toolbox on Mac -keywords: docker, documentation, install, toolbox, mac -title: Install Docker Toolbox on macOS ---- - -Docker Toolbox provides a way to use Docker on older Macs -that do not meet -minimal system requirements for [Docker Desktop for Mac](../docker-for-mac/index.md). - -## 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-specific -kernel features, you can't run Docker Engine natively on -macOS with Docker Toolbox. Instead, you must use the -Docker Machine command, `docker-machine`, to create and -attach to a small Linux VM on your machine. This VM hosts -Docker Engine for you on your Mac. - ->**Tip**: One of the advantages of the newer -[Docker Desktop for Mac](../docker-for-mac/index.md) solution is that -it uses native virtualization and does not require -VirtualBox to run Docker. - - -## Step 1: Check your version - -Your Mac must be running macOS 10.8 "Mountain Lion" or newer to run Docker -software. To find out what version of the OS you have: - -1. Choose **About this Mac** from the Apple menu. - - The version number appears directly below the words `macOS`. - -2. 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.14 Mojave or newer, consider using [Docker Desktop for - Mac](/docker-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](/docker-for-mac/#what-to-know-before-you-install). - -## Step 2: Install Docker Toolbox - -> **Note**: Docker are no longer maintaining the download.docker.com url for -> Docker Toolbox, therefore an unsigned warning (verified publisher dialog) is -> displayed during the installation process. - -1. To download the latest version of Docker Toolbox, go to [Toolbox - Releases](https://github.com/docker/toolbox/releases) and download the - latest `.pkg` file. - -2. Install Docker Toolbox by double-clicking the package or by right-clicking -and choosing "Open" from the pop-up menu. - - The installer launches an introductory dialog, followed by an overview of what's installed. - - ![Install Docker Toolbox](images/mac-welcome-page.png) - -3. Press **Continue** to install the toolbox. - - The installer presents you with options to customize the standard - installation. - - ![Standard install](images/mac-page-two.png) - - 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. - -4. Press **Install** to perform the standard installation. - - The system prompts you for your password. - - ![Password prompt](images/mac-password-prompt.png) - -5. 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**. - - ![Quickstart](images/mac-page-quickstart.png) - - Then click **Close** to finish the installer. - - ![All finished](images/mac-page-finished.png) - - -## 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 any -Virtual Box VM, it maintains its configuration between uses. - -1. Open the **Launchpad** and locate the Docker Quickstart Terminal icon. - - ![Launchpad](images/applications_folder.png) - -2. 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. - - ``` - Last login: Sat Jul 11 20:09:45 on ttys002 - bash '/Applications/Docker Quickstart Terminal.app/Contents/Resources/Scripts/start.sh' - Get http:///var/run/docker.sock/v1.19/images/json?all=1&filters=%7B%22dangling%22%3A%5B%22true%22%5D%7D: dial unix /var/run/docker.sock: no such file or directory. Are you trying to connect to a TLS-enabled daemon without TLS? - Get http:///var/run/docker.sock/v1.19/images/json?all=1: dial unix /var/run/docker.sock: no such file or directory. Are you trying to connect to a TLS-enabled daemon without TLS? - -bash: lolcat: command not found - - mary at meepers in ~ - $ bash '/Applications/Docker Quickstart Terminal.app/Contents/Resources/Scripts/start.sh' - Creating Machine dev... - Creating VirtualBox VM... - Creating SSH key... - Starting VirtualBox VM... - Starting VM... - To see how to connect Docker to this machine, run: docker-machine env dev - Starting machine dev... - Setting environment variables for machine dev... - - ## . - ## ## ## == - ## ## ## ## ## === - /"""""""""""""""""\___/ === - ~~~ {~~ ~~~~ ~~~ ~~~~ ~~~ ~ / ===- ~~~ - \______ o __/ - \ \ __/ - \____\_______/ - - The Docker Quick Start Terminal is configured to use Docker with the "default" VM. - ``` - -3. 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. - - ![Terminal](images/terminal.png) - - The prompt is traditionally a `$` dollar sign. You type commands into the - *command line* which is the area after the prompt. Your cursor is indicated - by a highlighted area or a `|` that appears in the command line. After - typing a command, always press RETURN. - -4. 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: - - $ docker run hello-world - Unable to find image 'hello-world:latest' locally - latest: Pulling from library/hello-world - 535020c3e8ad: Pull complete - af340544ed62: Pull complete - Digest: sha256:a68868bfe696c00866942e8f5ca39e3e31b79c1e50feaee4ce5e28df2f051d5c - Status: Downloaded newer image for hello-world:latest - - Hello from Docker. - This message shows that your installation appears to be working correctly. - - To generate this message, Docker took the following steps: - 1. The Docker Engine CLI client contacted the Docker Engine daemon. - 2. The Docker Engine daemon pulled the "hello-world" image from the Docker Hub. - 3. The Docker Engine daemon created a new container from that image which runs the - executable that produces the output you are currently reading. - 4. The Docker Engine daemon streamed that output to the Docker Engine CLI client, which sent it - to your terminal. - - To try something more ambitious, you can run an Ubuntu container with: - $ docker run -it ubuntu bash - - Share images, automate workflows, and more with a free Docker Hub account: - https://hub.docker.com - - For more examples and ideas, visit: - https://docs.docker.com/userguide/ - -## Optional: Add shared directories - -By default, Toolbox only has access to the `/Users` directory and mounts it into -the VMs at `/Users`. If your project lives elsewhere or needs access to other -directories on the host filesystem, you can add them. - -### Use the VirtualBox GUI - -You can configure shared folders in the VirtualBox UI. - -1. Open the VirtualBox UI. - -2. Click the **Settings** gear, then go to **Shared Folders**. - -3. Select any existing listing under **Machine Folders**, then - click the **+** icon. - - * Choose the **Folder Path** on the host, enter the **Folder Name** - for within the VM (or take the default, which is the same name - as on the host), and configure any additional options you need. - - * Choose **Auto-mount** if you want the folder to automatically - be mounted into the VM, and choose **Make Permanent** for it - to be considered a permanently shared folder. - -4. Click **OK** to add the new folder to the Shared Folders list. - -5. 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: - -```bash -$ mount -t vboxsf -o uid=1000,gid=50 your-other-share-name /some/mount/location -``` - -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 using -> the 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 machines -you created with Docker Machine. In some cases, you might want to keep -machines created with Docker Machine. - -For example, if you plan to re-install Docker Machine as a part of -Docker Desktop for Mac you can continue to manage those machines through -Docker. Or, if you have remote machines on a cloud provider and you -plan to manage them using the provider, you wouldn't want to remove -them. So the step to remove machines is described here as optional. - -To uninstall Toolbox on a Mac, do the following: - -1. List your machines. - - ``` - $ docker-machine ls - NAME ACTIVE DRIVER STATE URL SWARM - dev * virtualbox Running tcp://192.168.99.100:2376 - my-docker-machine virtualbox Stopped - default virtualbox Stopped - ``` - -2. Optionally, remove each machine. For example: - - ``` - $ docker-machine rm my-docker-machine - Successfully removed my-docker-machine - ``` - - This step is optional because if you plan - to re-install Docker Machine as a part - of [Docker Desktop for Mac](../docker-for-mac/index.md), you can import and - continue to manage those machines through Docker. - -3. In your "Applications" folder, remove the "Docker" directory, - which contains "Docker Quickstart Terminal" and "Kitematic". - -4. Run the following in a command shell to fully remove Kitematic: - - ``` - $ rm -fr ~/Library/Application\ Support/Kitematic - ``` - -5. Remove the `docker`, `docker-compose`, and `docker-machine` commands from - the `/usr/local/bin` folder. Docker Desktop for Mac and Brew may also have - installed them; in case of doubt leave them, or reinstall them via Brew, or - rerun Docker Desktop for Mac (no need to reinstall it). - - ``` - $ rm -f /usr/local/bin/docker - $ rm -f /usr/local/bin/docker-compose - $ rm -f /usr/local/bin/docker-machine - ``` - -6. Optionally, remove the `~/.docker/machine` directory. - - This directory stores some configuration and/or state, such as information - about created machines and certificates. - -7. Uninstall Oracle VirtualBox, which is installed as a part of the - Toolbox install. - -## Next steps - -* Try the [Get started](../get-started/index.md) tutorial. - -* Dig in deeper with [more tutorials and examples](../engine/tutorials/index.md) on building images, running containers, networking, managing data, and storing images on Docker Hub. - -* [Learn about Kitematic](../kitematic/userguide.md) - -* [Learn about Docker Machine](../machine/overview.md) - -* [Learn about Docker Compose](../compose/index.md) diff --git a/toolbox/toolbox_install_windows.md b/toolbox/toolbox_install_windows.md deleted file mode 100644 index bced749d62..0000000000 --- a/toolbox/toolbox_install_windows.md +++ /dev/null @@ -1,284 +0,0 @@ ---- -advisory: toolbox -description: How to install Toolbox on Mac -keywords: docker, documentation, install, toolbox, win -title: Install Docker Toolbox on Windows ---- - -Docker Toolbox provides a way to use Docker on Windows systems that do not meet -minimal system requirements for the [Docker Desktop for Windows](../docker-for-windows/index.md) -app. - -## 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 Windows 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-specific -kernel features, you can't run Docker Engine natively -on Windows. Instead, you must use the Docker Machine -command, `docker-machine`, to create and attach to a -small Linux VM on your machine. This VM hosts Docker Engine -for you on your Windows system. - ->**Tip**: One of the advantages of the newer -[Docker Desktop for Windows](../docker-for-windows/index.md) solution is that -it uses native virtualization and does not require -VirtualBox to run Docker. - -## Step 1: Check your version - -To run Docker, your machine must have a 64-bit operating system running Windows 7 or higher. Additionally, you must make sure that virtualization is enabled on your machine. -To verify your machine meets these requirements, do the following: - -1. Right click the windows message and choose **System**. - - If you aren't using a supported version, you could consider upgrading your - operating system. - - If you have a recent version of Windows, - consider using [Docker Desktop for Windows](/docker-for-windows) instead. It runs - natively on the Windows, so there is no need for a pre-configured Docker - QuickStart shell. It also uses Hyper-V for virtualization, so the - instructions below for checking virtualization will be out of date for newer - Windows systems. Full install prerequisites are provided in the Docker Desktop for - Windows topic in [What to know before you - install](/docker-for-windows/#what-to-know-before-you-install). - -2. Make sure your Windows system supports Hardware Virtualization Technology and that virtualization is enabled. - -
- **For Windows 10** - - Run [Speccy](https://www.piriform.com/speccy){: target="_blank" rel="noopener" class="_"}, and look at the CPU information. - -
- **For Windows 8 or 8.1** - - Choose **Start > Task Manager** and navigate to the **Performance** tab. - Under **CPU** you should see the following: - - ![Release page](images/virtualization.png) - - If virtualization is not enabled on your system, follow the manufacturer's instructions for enabling it. - -
- **For Windows 7** - - Run a tool like the [Microsoft® Hardware-Assisted Virtualization Detection Tool](https://www.microsoft.com/en-us/download/details.aspx?id=592){: target="_blank" rel="noopener" class="_"} or [Speccy](https://www.piriform.com/speccy){: target="_blank" rel="noopener" class="_"}, and follow the on-screen instructions. -

-3. Verify your Windows OS is 64-bit (x64) - - How you do this verification depends on your Windows version. - For details, see the Windows article [How to determine whether - a computer is running a 32-bit version or 64-bit version of the - Windows operating system](https://support.microsoft.com/en-us/kb/827218). - -## Step 2: Install Docker Toolbox - -In this section, you install the Docker Toolbox software and several "helper" applications. The installation adds the following software to your machine: - -* Docker Client for Windows -* Docker Toolbox management tool and ISO -* Oracle VM VirtualBox -* Git MSYS-git UNIX tools - -If you have a previous version of VirtualBox installed, do not reinstall it with the Docker Toolbox installer. When prompted, uncheck it. - -If you have Virtual Box running, you must shut it down before running the -installer. - -> **Note**: Docker no longer maintains the download.docker.com url for -> Docker Toolbox, therefore an unsigned warning (verified publisher dialog) is -> displayed during the installation process. - -1. To download the latest version of Docker Toolbox, go to [Toolbox - Releases](https://github.com/docker/toolbox/releases) and download the - latest `.exe` file. - -2. Install Docker Toolbox by double-clicking the installer. - - The installer launches the "Setup - Docker Toolbox" dialog. - - If Windows security dialog prompts you to allow the program to make a - change, choose **Yes**. The system displays the **Setup - Docker Toolbox for - Windows** wizard. - - ![Release page](images/installer_open.png) - -3. Press **Next** to accept all the defaults and then **Install**. - - Accept all the installer defaults. The installer takes a few minutes to install all the components: - -4. When notified by Windows Security the installer will make changes, make sure you allow the installer to make the necessary changes. - - When it completes, the installer reports it was successful: - - ![Success](images/finish.png) - -5. Uncheck "View Shortcuts in File Explorer" and press **Finish**. - - -## Step 3: Verify your installation - -The installer adds Docker Toolbox, VirtualBox, and Kitematic to your -**Applications** folder. In this step, you start Docker Toolbox and run a simple -Docker command. - -1. On your Desktop, find the Docker QuickStart Terminal icon. - - ![Desktop](images/icon-set.png) - -2. Click the Docker QuickStart icon to launch a pre-configured Docker Toolbox terminal. - - If the system displays a **User Account Control** prompt to allow VirtualBox to make changes to your computer. Choose **Yes**. - - The terminal does several things to set up Docker Toolbox for you. When it is done, the terminal displays the `$` prompt. - - ![Desktop](images/b2d_shell.png) - - The terminal runs a special `bash` environment instead of the standard Windows command prompt. The `bash` environment is required by Docker. - -3. Make the terminal active by clicking your mouse next to the `$` prompt. - - If you aren't familiar with a terminal window, here are some quick tips. - - ![/Terminal shell](images/b2d_shell.png) - - The prompt is traditionally a `$` dollar sign. You type commands into the - *command line* which is the area after the prompt. Your cursor is indicated - by a highlighted area or a `|` that appears in the command line. After - typing a command, always press RETURN. - -4. 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: - - $ docker run hello-world - Unable to find image 'hello-world:latest' locally - Pulling repository hello-world - 91c95931e552: Download complete - a8219747be10: Download complete - Status: Downloaded newer image for hello-world:latest - Hello from Docker. - This message shows that your installation appears to be working correctly. - - To generate this message, Docker took the following steps: - 1. The Docker Engine CLI client contacted the Docker Engine daemon. - 2. The Docker Engine daemon pulled the "hello-world" image from the Docker Hub. - (Assuming it was not already locally available.) - 3. The Docker Engine daemon created a new container from that image which runs the - executable that produces the output you are currently reading. - 4. The Docker Engine daemon streamed that output to the Docker Engine CLI client, which sent it - to your terminal. - - To try something more ambitious, you can run an Ubuntu container with: - $ docker run -it ubuntu bash - - For more examples and ideas, visit: - https://docs.docker.com/userguide/ - -## Looking for troubleshooting help? - -Typically, the above steps work out-of-the-box, but some scenarios can cause problems. If your `docker run hello-world` didn't work and resulted in errors, check out [Troubleshooting](faqs/troubleshoot.md) for quick fixes to common problems. - -A Windows specific problem you might encounter relates to the NDIS6 host network filter driver, which is known to cause issues on some Windows -versions. For Windows Vista systems and newer, VirtualBox installs NDIS6 driver by default. Issues can range from system slowdowns to networking problems for the virtual machine (VM). If you notice problems, **re-run the Docker Toolbox installer**, and select the option to _**install VirtualBox with the NDIS5 driver**_. - -## Optional: Add shared directories - -By default, Toolbox only has access to the `C:\Users` directory and mounts it into -the VMs at `/c/Users`. - -> **Note**: Within the VM path, `c` is lowercase and the `Users` is capitalized. - -If your project lives elsewhere or needs access to other -directories on the host filesystem, you can add them, using the VirtualBox UI. - -1. Open the VirtualBox UI. - -2. Click the **Settings** gear, then go to **Shared Folders**. - -3. Select any existing listing under **Machine Folders**, then - click the **+** icon. - - * Choose the **Folder Path** on the host, enter the **Folder Name** - for within the VM (or take the default, which is the same name - as on the host), and configure any additional options you need. - - * Choose **Auto-mount** if you want the folder to automatically - be mounted into the VM, and choose **Make Permanent** for it - to be considered a permanently shared folder. - -4. Click **OK** to add the new folder to the Shared Folders list. - -5. Click **OK** again to save your changes and exit the Settings dialog. - -## How to uninstall Toolbox - -Removing Toolbox involves removing all the Docker components it includes. - -A full uninstall also includes removing the local and remote machines you created with Docker Machine. In some cases, you might want to keep machines created with Docker Machine. - -For example, if you plan to re-install Docker Machine as a part of Docker Desktop for Windows you can continue to manage those machines through Docker. Or, if you have remote machines on a cloud provider and you plan to manage them using the provider, you wouldn't want to remove them. So the step to remove machines is described here as optional. - -To uninstall Toolbox on Windows, do the following: - -1. List your machines. - - ``` - $ docker-machine ls - NAME ACTIVE DRIVER STATE URL SWARM - dev * virtualbox Running tcp://192.168.99.100:2376 - my-docker-machine virtualbox Stopped - default virtualbox Stopped - ``` - -2. Optionally, remove each machine. For example: - - ``` - $ docker-machine rm my-docker-machine - Successfully removed my-docker-machine - ``` - - This step is optional because if you plan to re-install Docker Machine as a - part of [Docker Desktop for Windows](../docker-for-windows/index.md), you can - import and continue to manage those machines through Docker. - -3. Uninstall Docker Toolbox using Window's standard process for uninstalling programs through the control panel (programs and features). - - >**Note**: This process does not remove the `docker-install.exe` file. You must delete that file yourself. - -5. Optionally, remove the -`C:\Users\\.docker` directory. - - If you want to remove Docker entirely, you - can verify that the uninstall removed - the `.docker` directory under your user path. - If it is still there, remove it manually. - This directory stores some Docker - program configuration and state, such as - information about created machines and - certificates. You usually don't need to remove this directory. - -6. Uninstall Oracle VirtualBox, which is - installed as a part of the Toolbox install. - -## Next steps - -* Try out the [Get started](../get-started/index.md) tutorial. - -* Dig in deeper with [more tutorials and examples](../engine/tutorials/index.md) on building images, running containers, networking, managing data, and storing images on Docker Hub. - -* [Learn about Kitematic](../kitematic/userguide.md) - -* [Learn about Docker Machine](../machine/overview.md) - -* [Learn about Docker Compose](../compose/index.md)