├── .gitignore ├── LICENSE └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | run-docker-external.code-workspace -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2018 Ryan 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Run Docker External Storage in macOS 10.13+ 2 | Docker can be used to test projects without having to install and orchestrate software locally. However, if you're running a setup with a smaller internal drive it can be useful to move these stores externally. Newer Macs with smaller internal storage ~~soldered to the board~~ provide a challenge to developers. This tutorial will explain how to setup an external disk to store docker images and containers. 3 | 4 | This solution was suggested in this "[Docker Forum Post](https://forums.docker.com/t/change-docker-image-directory-for-mac/18891/8)" 5 | 6 | ## Limitations 7 | The limited to MacOS 10.14: Mojave+ and with Docket Desktop. This tutorial assumes that the file locations are the same as the default locations used by Docker on macOS. Please create an issue if this does not work with a version of macOS or Docker. 8 | 9 | *Docker will not start if your external storage is formatted with FAT or exFAT you should use a APFS disk.* See [issue](https://github.com/wattry/run-docker-external-storage/issues/8). Use diskutil to reformat your disk before you continue. 10 | 11 | ## Setup 12 | This section will detail the process pre and post the installation of Docker 13 | 14 | 1. Setup the external drive's symbolic links. 15 | 16 | This step reproduces a similar structure to the internal storage, making it easier to debug or use documentation. You can use whichever directory structure you chose, just ensure you're consistent throughout the tutorial. 17 | 18 | * Using your shell or GUI create navigate to the root your external drive. 19 | * Create the following folder structure: 20 | 21 | ```shell 22 | mkdir -p "Users/$(whoami)/Library/Containers" 23 | ``` 24 | 25 | The p option on the mkdir command will, recursively, create the entire path's directory structure. 26 | 27 | 1. Create environment variables 28 | This step is optional however it will make it easier to reference the external location. 29 | 30 | Create/Open the config file for your shell. Newer Macs will use zsh by default though you will find a .zshrc or .bashrc. You can run `echo $SHELL` to find your default shell. These are suggestions and you can name your variables whatever you like. In this case $E stands for external and $EHOME for external home. These allow you to cd into and have a consistent source of truth, though this step is not required. 31 | 32 | ``` shell 33 | ## Env variables 34 | export E="/Volumes/" 35 | export EHOME="$E/${HOME}" 36 | ``` 37 | 38 | 1. Create Symbolic links 39 | ``` shell 40 | # Create a symlink to External Drive to preserve internal drive. 41 | ln -s "${EHOME}/Library/Containers/com.docker.docker" "/Users/$(whoami)/Library/Containers" 42 | ``` 43 | 44 | 1. Then either close and reopen your shell or reload your config with the following command 45 | 46 | ``` shell 47 | source .bash_profile 48 | or 49 | source .bashrc 50 | or 51 | source .zshrc 52 | ``` 53 | 54 | Test your links and env variables 55 | ```shell 56 | $ echo $E 57 | /Volumes/ 58 | $ echo $EHOME 59 | /Volumes//Users/ 60 | $ ls -la /Users/$(whoami)/Library/Containers/com.docker.docker 61 | lrwxr-xr-x 1 staff 74 Jan 1 00:00 com.docker.docker -> /Volumes//Users//Library/Containers/com.docker.docker 62 | ``` 63 | Your environment should now be ready. 64 | 65 | ## Pre Docker Installation 66 | If you're using homebrew you can run `brew install docker-desktop` or download it [Download and install Docker CE for macOS](https://docs.docker.com/docker-for-mac/install/). 67 | 68 | ## Post Docker Install 69 | 70 | This setup can be performed using cp/rsync or mv to get the com.docker.docker directory and content to your external drive. rsync will transfer the port files which mv will not (mv/cp will throw the following error *"Cannot listen: ~/Library/Containers/com.docker.docker/Data/vms/0/: failed bind: Permission denied"*). This will not prevent you from copying as you can ignore this; these files are created when the docker daemon starts up. 71 | 72 | 1. Find where docker stores images: 73 | 74 | Run the following command to see if Docker is running: 75 | 76 | ``` 77 | launchctl list | grep docker 78 | - 0 com.docker.helper 79 | 1949 0 com.docker.docker.2716 80 | ``` 81 | 82 | 1. If docker is not started yet, start it using the application launcher. 83 | 1. Once it is running in the task bar secondary click on the docker icon at the top right of the screen. 84 | 1. Select preferences and select the disk tab. 85 | 1. Open a new shell 86 | 1. Type or autocomplete the path up to the com.docker.docker directory part. 87 | 1. If defaulted it should be located here *"/Users/\/Library/Containers/com.docker.docker"*. 88 | 1. Stop Docker by secondary clicking on the docker icon and selecting *"Quit Docker Desktop"* 89 | 90 | To check that docker is no longer running use the following command: 91 | ``` 92 | launchctl list | grep docker 93 | - 0 com.docker.helper 94 | ``` 95 | 96 | 2. Use mv or rsync to transfer the files. These steps may take a while to complete. Alternatively you can prune all the resources you do not need. 97 | 98 | ### Using mv 99 | ``` 100 | $ mv -v "${HOME}/Library/Containers/com.docker.docker" "${EHOME}/Library/Containers" 101 | ``` 102 | 103 | ### Using rsync 104 | ``` 105 | $ rsync -a -v "${HOME}/Library/Containers/com.docker.docker" "${EHOME}/Library/Containers" 106 | ``` 107 | 108 | Once this is complete make sure all the files have transferred run this command. If there is no difference there will be no output. If the only are only socket files, you need not worry. 109 | 110 | ``` 111 | diff --brief -r "${EHOME}/Library/Containers/com.docker.docker" "${HOME}/Library/Containers/com.docker.docker" 112 | ``` 113 | 114 | You should now be able to use Docker on an external device. 115 | --------------------------------------------------------------------------------