From 627b9f5e07fb6eebe884642a86cd4759c3b2f837 Mon Sep 17 00:00:00 2001 From: Leonid Makarov Date: Wed, 11 Nov 2015 12:08:18 -0500 Subject: [PATCH] Reorganized docs --- README.md | 262 ++++--------------------------------- docs/networking.md | 97 ++++++++++++++ docs/synced-folders.md | 42 ++++++ docs/tips.md | 33 +++++ docs/vm-settings.md | 10 ++ scripts/presetup-ubuntu.sh | 83 ++++++++++++ vagrant.yml | 12 +- 7 files changed, 295 insertions(+), 244 deletions(-) create mode 100644 docs/networking.md create mode 100644 docs/synced-folders.md create mode 100644 docs/tips.md create mode 100644 docs/vm-settings.md create mode 100644 scripts/presetup-ubuntu.sh diff --git a/README.md b/README.md index a344e0b..a4fba67 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,12 @@ # Boot2docker Vagrant Box Boot2docker Vagrant box for optimized Docker and Docker Compose use on Mac and Windows. + ## What is this? -This is a temporary solution to achieve better performance with synced folders and docker data volumes on Mac and Windows. -The stock boot2docker currently mounts host volumes via the default VirtualBox Guest Additions (vboxsf) mode, which is terribly slow. Much better performance can be achieved with NFS, SMB or rsync. + +This is a temporary solution to achieve better performance with synced folders and docker data volumes on Mac and Windows. + +The stock boot2docker/docker-machine mounts host volumes via VirtualBox Guest Additions (vboxsf) mode, which is is terribly slow. Much better performance can be achieved with **nfs** (Mac), **smb** (Windows) or **rsync** (Mac and Windows). ## Prerequisites @@ -11,10 +14,10 @@ The stock boot2docker currently mounts host volumes via the default VirtualBox G 2. [Vagrant](https://www.vagrantup.com/) 1.7.3+ 3. [Babun](http://babun.github.io) - A Linux-type shell, **Windows only** -Proceed to [Setup and usage](#setup) if you already have all prerequisites installed or prefer to install some/all manually. +For best result and a clean setup it is recommended to remove any previous versions of VirtualBox, Vagrant, boot2docker, docker and docker-compose. -Automatic **installation** and **updates** of prerequisites is available via the following one-liners. -Make sure to stop all VirtualBox VMs prior to performing updates. +Automatic **installation** and **updates** of prerequisites is available via the one-liners below. +**Make sure to stop all VirtualBox VMs prior to performing updates.** **Mac** @@ -24,265 +27,46 @@ Prerequisites are installed using **brew/cask** (brew and cask will be installed **Windows** -**On Windows you will need a good Linux-type shell. [Babun](http://babun.github.io) is a great option. All automated scripts and instructions in this project assume using Babun shell and were not tested with other CYGWIN shells.** +**All automated scripts and instructions in this project assume using Babun shell and are not tested with other shells.** Prerequisites are installed using **babun** and **chocolatey** (chocolatey will be installed if missing). -**Docker Compose will be installed natively on Windows via pip!** - -1. Download and install [Babun](http://babun.github.io) -2. Run the following in babun - - ``` bash <(curl -s https://raw.githubusercontent.com/blinkreaction/boot2docker-vagrant/master/scripts/presetup-win.sh) - ``` + ## Setup and usage -### Automatic installation (Mac and Windows) +### Automatic installation -Run the following command within your `` (shared boo2docker VM for multiple projects, recommended) or `` (dedicated boot2docker VM) directory: +Designate a root folder that the VM will have access to (e.g. `~/Projects`) and run there: bash <(curl -s https://raw.githubusercontent.com/blinkreaction/boot2docker-vagrant/master/scripts/setup.sh) -### Manual installation (Mac and Windows) +### Manual installation -1. Copy `Vagrantfile` and `vagrant.yml` files from this repo into your `` (shared boo2docker VM for multiple projects, recommended) or `` (dedicated boot2docker VM) directory. -2. Rename `vagrant.yml.dist` to `vagrant.yml` -3. Launch Terminal (Mac) or Babun (Windows) -4. cd to ``, start the VM +1. Copy `Vagrantfile` and `vagrant.yml` into a designated folder +2. Inside the folder run ``` - cd vagrant up ``` -5. Verify installation +3. Verify your setup by checking docker client and server versions - ``` + ``` docker version - docker-compose --version ``` - -## Synced Folders options - -This box supports all [Synced Folder](http://docs.vagrantup.com/v2/synced-folders/) options provided by Vagrant: -- vboxsf - native VirtualBox method, cross-platform, convenient and reliable, terribly slow -- NFS - better performance and convenience for Mac -- SMB - better performance and convenience for Windows (on par with NFS on Mac) -- rsync - best performance, cross-platform, one-way only - -Follow the instructions in the `vagrant.yml` file to switch between different sync options. -The best balance between performance and convenience can be achieved with NFS on Mac (default) and SMB on Windows (not default). - -Additional steps are required to get SMB or rsync to work on Windows. [See below](#synced-folders-win). - -In addition to the stock SMB synced folders option this box provides an experimental one: [SMB2](#synced-folders-smb2). -With the **SMB2** option you will receive several "elevated command prompt" prompts which you accept. -No need to enter usernames and passwords unlike the stock SMB option Vagrant ships with. - -If you use rsync, you'll have to run `vagrant rsync-auto` in a separate terminal to keep the files in sync as you make changes. - - -### Mac - -Option comparison for Mac Drupal developers (using `time drush si -y` as a test case): -- vboxsf: 6x (slowest) -- NFS: 1.3x -- rsync: 1x (fastest) - -NFS provides good performance and convenience. It is the default and recommended option on Mac. - - -### Windows - -Option comparison for Windows Drupal developers (using `time drush si -y` as a test case): -- vboxsf: 5x (slowest) -- SMB: 2x -- rsync: 1x (fastest) - -SMB provides good performance and convenience. It is the recommended option, but NOT the default one on Windows. - -**Enabling SMB** - -To use the SMB synced folder type: - -1. Stop the VM with: `vagrant halt` -2. Choose `smb` as the sync type in the `vagrant.yml` file. -3. Launch Git Bash as an administrator -4. Start the VM: `vagrant up` - -While using SMB you have to control Vagrant from an elevated (run as admin) Git Bash shell. - - -**SMB2 (experimental option)** - -This is an experimental option. -Compared to **SMB**, **SMB2** does not require running vagrant as admin and does not prompt for username and password. -You will receive several "elevated command prompt" prompts which you accept. -Vagrant will automatically create a user, set correct file permissions, create the SMB share, and mount it. - -**Enabling rsync** - -rsync is not natively available on Windows. -Git for Windows comes with Git Bash shell, which is based on [MinGW/MSYS](http://www.mingw.org/wiki/msys). -MSYS has a package for rsync, which can be installed and accessed via Git Bash. - -To use rsync on Windows: - -1. Download and extract the content on this [archive](https://drive.google.com/open?id=0B130F0xKxOWCTUN1d3djZGZ0M2M&authuser=0) into the `bin` directory of your Git installation (e.g. `c:\Program Files (x86)\Git\bin\`). -2. Choose `rsync` as the sync type in the `vagrant.yml` file. -3. Provide an explicit list of folders to sync in the `vagrant.yml` file (`folders` sequence). -4. Reload the VM: `vagrant reload` -5. Run `vagrant rsync-auto` to keep the files in sync as you make changes. - - -## VirtualBox VM settings - -Open `vagrant.yml` file and edit respective values. - -- `v.gui` - Set to `true` for debugging. This will unhide VM's primary console screen. Default: `false`. -- `v.memory` - Memory settings (MB). Default: `2048`. -- `v.cpus: 1` - number of virtual CPU cores. Default: `1`. - -Please note, VirtualBox works much better with a single CPU in most cases, this it is not recommended to change the `v.cpus` value. - - -## Network settings - -The default box private network IP is `192.168.10.10`. -To map additional IP addresses for use with multiple projects open `vagrant.yml` and ucomment respective lines: - -```yaml -hosts: - - ip: 192.168.10.11 - - ip: 192.168.10.12 - - ip: 192.168.10.13 -``` - -Project specific `:` mapping for containers is done in via docker-compose in `docker-compose.yml` - - -## vhost-proxy - -As an alternative to using dedicated IPs for different projects a built-in vhost-proxy container can be used. -It binds to `192.168.10.10:80` (the default box IP address) and routes web requests based on the `Host` header. - -### How to use -- Set `vhost_proxy: true` in your vagrant.yml file and do a 'vagrant reload' -- Set the `VIRTUAL_HOST` environment variable for the web container in your setup (e.g. `VIRTUAL_HOST=example.com`) -- Add an entry in your hosts file (e.g. `/etc/hosts`) to point the domain to the default box IP (`192.168.10.10`) - - As an alternative see [Wildcard DNS](#dns) instructions below -- Multiple domain names can be separated by comas: `VIRTUAL_HOST=example.com,www.example.com` - -Example docker run - -``` -docker run --name nginx -d -e "VIRTUAL_HOST=example.com" nginx:latest -``` - -Example docker-compose.yml entry - -``` -# Web node -web: - image: nginx:latest - ports: - - "80" - environment: - - VIRTUAL_HOST=example.com -``` - -Example hosts file entry - -``` -192.168.10.10 example.com -``` - -It is completely fine to use both the vhost-proxy approach and the dedicated IPs approach concurently: - - `"80"` - expose port "80", docker will randomly pick an available port on the Docker Host - - `"192.168.10.11:80:80"` - dedicated IP:port mapping - - -## DNS and service discovery - -### DNS resolution - -The built-in `dns` container can be used to resolve all `*.drude` domain names to `192.168.10.10` (VM's primary IP address), where vhost-proxy listens on port 80. - -**Mac** - -``` -sudo mkdir -p /etc/resolver -echo -e "\n# .drude domain resolution\nnameserver 192.168.10.10" | sudo tee -a /etc/resolver/drude -``` - -**Windows** - -On Windows add `192.168.10.10` as the primary DNS server and your LAN/ISP/Google DNS as secondary. - - -### Service discovery - -The built-in `dns` container can also be used for local DNS based service discovery. -You can define an arbitrary domain name via the `DOMAIN_NAME` environment variable for any container and it will be resolved to the internal IP address of that container. - -**Example** - -``` -docker run --name nginx -d -e "DOMAIN_NAME=my-project.web.docker" nginx:latest -docker run busybox ping my-project.web.docker -c 1 -``` - -``` -PING my_project.web.docker (172.17.42.8): 56 data bytes -64 bytes from 172.17.42.8: seq=0 ttl=64 time=0.052 ms -... - -``` - -Multiple domain names can be separated by comas: `DOMAIN_NAME=my-project.web.docker,www.my-project.web.docker` - -## Tips - -### Automate DOCKER_HOST variable export - -This is only necessary for manual instllations. On Mac the [setup.sh](setup.sh) scripts takes care of this for you. - -Add the following in your .bashrc, .zshrc, etc. file to automate the environment variable export: - - # Docker (default for Vagrant based boxes) - export DOCKER_HOST=tcp://localhost:2375 - -If you also have `$(boot2docker shellinit)` there, then make sure those lines go BEFORE it, e.g.: - - # Docker (default for Vagrant based boxes) - export DOCKER_HOST=tcp://localhost:2375 - - # boot2docker shellinit - $(boot2docker shellinit) - -This way if boot2docker is NOT running, your `DOCKER_HOST` will default to `tcp://localhost:2375`. -Otherwise `$(boot2docker shellinit)` will overwrite the variables and set `DOCKER_HOST` to point to the boot2docker VM. - -### Vagrant control -Vagrant can be controlled (e.g. `vagrant up`, `vagrant ssh`, `vagrant reload`, etc.) from the root directory of the Vagrantfile as well as from any subdirectory. This is very usefull when working with multiple projects in subdirectories. - -### Sublime Text 3 users -Add this to your user settings (Sublime Text > Preferences > Settings - User): - - { - "atomic_save": false - } -ST3 does not update the ctime extended file attribute when saving a file. This leads to NFS not seeing the changes in a file unless the file size changes as well (i.e. changing a single symbol in a file with ST3 will not be visible over NFS). The setting above fixes that. +## Documentation - -## troubleshooting +- [Synced folders](docs/synced-folders.md) +- [VirtualBox VM settings](docs/vm-settings.md) +- [Networking](docs/networking.md) +- [Troubleshooting](docs/troubleshooting.md) +- [Tips](docs/tips.md) -See [Troubleshooting](docs/troubleshooting.md) section of the docs. ## License diff --git a/docs/networking.md b/docs/networking.md new file mode 100644 index 0000000..bc6f973 --- /dev/null +++ b/docs/networking.md @@ -0,0 +1,97 @@ +# Networking + + +## VM network settings + +The default box private network IP is `192.168.10.10`. +To map additional IP addresses for use with multiple projects open `vagrant.yml` and ucomment respective lines: + +```yaml +hosts: + - ip: 192.168.10.11 + - ip: 192.168.10.12 + - ip: 192.168.10.13 +``` + +Project specific `:` mapping for containers is done in via docker-compose in `docker-compose.yml` + + +## vhost-proxy + +As an alternative to using dedicated IPs for different projects a built-in vhost-proxy container can be used. +It binds to `192.168.10.10:80` (the default box IP address) and routes web requests based on the `Host` header. + +### How to use +- Set `vhost_proxy: true` in your vagrant.yml file and do a 'vagrant reload' +- Set the `VIRTUAL_HOST` environment variable for the web container in your setup (e.g. `VIRTUAL_HOST=example.com`) +- Add an entry in your hosts file (e.g. `/etc/hosts`) to point the domain to the default box IP (`192.168.10.10`) + - As an alternative see [Wildcard DNS](#dns) instructions below +- Multiple domain names can be separated by comas: `VIRTUAL_HOST=example.com,www.example.com` + +Example docker run + +``` +docker run --name nginx -d -e "VIRTUAL_HOST=example.com" nginx:latest +``` + +Example docker-compose.yml entry + +``` +# Web node +web: + image: nginx:latest + ports: + - "80" + environment: + - VIRTUAL_HOST=example.com +``` + +Example hosts file entry + +``` +192.168.10.10 example.com +``` + +It is completely fine to use both the vhost-proxy approach and the dedicated IPs approach concurently: + - `"80"` - expose port "80", docker will randomly pick an available port on the Docker Host + - `"192.168.10.11:80:80"` - dedicated IP:port mapping + + +## DNS and service discovery + +### DNS resolution + +The built-in `dns` container can be used to resolve all `*.drude` domain names to `192.168.10.10` (VM's primary IP address), where vhost-proxy listens on port 80. + +**Mac** + +``` +sudo mkdir -p /etc/resolver +echo -e "\n# .drude domain resolution\nnameserver 192.168.10.10" | sudo tee -a /etc/resolver/drude +``` + +**Windows** + +On Windows add `192.168.10.10` as the primary DNS server and your LAN/ISP/Google DNS as secondary. + + +### Service discovery + +The built-in `dns` container can also be used for local DNS based service discovery. +You can define an arbitrary domain name via the `DOMAIN_NAME` environment variable for any container and it will be resolved to the internal IP address of that container. + +**Example** + +``` +docker run --name nginx -d -e "DOMAIN_NAME=my-project.web.docker" nginx:latest +docker run busybox ping my-project.web.docker -c 1 +``` + +``` +PING my_project.web.docker (172.17.42.8): 56 data bytes +64 bytes from 172.17.42.8: seq=0 ttl=64 time=0.052 ms +... + +``` + +Multiple domain names can be separated by comas: `DOMAIN_NAME=my-project.web.docker,www.my-project.web.docker` diff --git a/docs/synced-folders.md b/docs/synced-folders.md new file mode 100644 index 0000000..c7069f0 --- /dev/null +++ b/docs/synced-folders.md @@ -0,0 +1,42 @@ +# Synced Folders + +This box supports all [Synced Folder](http://docs.vagrantup.com/v2/synced-folders/) options provided by Vagrant +as well two custom optimized options : +- vboxsf - native VirtualBox method, cross-platform, convenient and reliable, terribly slow +- nfs: better performance and convenience on Mac +- nfs2: optimized nfs settings, experimental (default on Mac) +- smb: better performance and convenience on Windows. Requires Vagrant to be run with admin privileges (not recommended). +- smb2: does not require running vagrant as admin (default on Windows). +- rsync: best performance, cross-platform platform, one-way only + +Follow the instructions in the `vagrant.yml` file to switch between different sync options. +The best balance between performance and convenience can be achieved with **nfs2** on Mac (default) and **smb2** on Windows (default). + +If you use rsync on Windows, you'll have to run `vagrant gatling-rsync-auto` in a separate terminal to keep the files in sync as you make changes. +This is automated on Mac with `rsync_auto` set to `true` in `vagrant.yml`. + + +## Mac + +Option comparison for Mac Drupal developers (using `time drush si -y` as a test case): +- vboxsf: 6x (slowest) +- nfs: 1.3x +- rsync: 1x (fastest) + +NFS provides good performance and convenience (used by default on Mac) + + +## Windows + +Option comparison for Windows Drupal developers (using `time drush si -y` as a test case): +- vboxsf: 5x (slowest) +- smb: 2x +- rsync: 1x (fastest) + +**smb** provides good performance and convenience (used by default on Windows) + +**smb vs smb2** + +Compared to **smb**, **smb2** does not require running vagrant as admin and does not prompt for username and password. +You will receive several "elevated command prompt" prompts which you accept. +Vagrant will automatically create a user, set correct file permissions, create the SMB share, and mount it. diff --git a/docs/tips.md b/docs/tips.md new file mode 100644 index 0000000..5581dcc --- /dev/null +++ b/docs/tips.md @@ -0,0 +1,33 @@ +# Tips + +## Automate DOCKER_HOST variable export + +This is only necessary for manual instllations. [setup.sh](../scripts/setup.sh) script takes care of this for you. + +Add the following in your .bashrc, .zshrc, etc. file to automate the environment variable export: + + # Docker (default for Vagrant based boxes) + export DOCKER_HOST=tcp://localhost:2375 + +If you also have `$(boot2docker shellinit)` there, then make sure those lines go BEFORE it, e.g.: + + # Docker (default for Vagrant based boxes) + export DOCKER_HOST=tcp://localhost:2375 + + # boot2docker shellinit + $(boot2docker shellinit) + +This way if boot2docker is NOT running, your `DOCKER_HOST` will default to `tcp://localhost:2375`. +Otherwise `$(boot2docker shellinit)` will overwrite the variables and set `DOCKER_HOST` to point to the boot2docker VM. + +## Vagrant control +Vagrant can be controlled (e.g. `vagrant up`, `vagrant ssh`, `vagrant reload`, etc.) from the root directory of the Vagrantfile as well as from any subdirectory. This is very usefull when working with multiple projects in subdirectories. + +## Sublime Text 3 users +Add this to your user settings (Sublime Text > Preferences > Settings - User): + + { + "atomic_save": false + } + +ST3 does not update the ctime extended file attribute when saving a file. This leads to NFS not seeing the changes in a file unless the file size changes as well (i.e. changing a single symbol in a file with ST3 will not be visible over NFS). The setting above fixes that. diff --git a/docs/vm-settings.md b/docs/vm-settings.md new file mode 100644 index 0000000..d9c7b1c --- /dev/null +++ b/docs/vm-settings.md @@ -0,0 +1,10 @@ + +# VirtualBox VM settings + +Open `vagrant.yml` file and edit respective values. + +- `v.gui` - Set to `true` for debugging. This will unhide VM's primary console screen. Default: `false`. +- `v.memory` - Memory settings (MB). Default: `2048`. +- `v.cpus: 1` - number of virtual CPU cores. Default: `1`. + +Please note, VirtualBox works much better with a single CPU in most cases, this it is not recommended to change the `v.cpus` value. diff --git a/scripts/presetup-ubuntu.sh b/scripts/presetup-ubuntu.sh new file mode 100644 index 0000000..d231599 --- /dev/null +++ b/scripts/presetup-ubuntu.sh @@ -0,0 +1,83 @@ +#!/bin/bash + +DOCKER_VERSION=1.9.0 +DOCKER_COMPOSE_VERSION=1.5.0 + +#-------------------------- Helper functions -------------------------------- + +# Console colors +red='\033[0;31m' +green='\033[0;32m' +yellow='\033[1;33m' +NC='\033[0m' + +echo-red () { echo -e "${red}$1${NC}"; } +echo-green () { echo -e "${green}$1${NC}"; } +echo-yellow () { echo -e "${yellow}$1${NC}"; } + +if_failed () +{ + if [ ! $? -eq 0 ]; then + if [[ "$1" == "" ]]; then msg="dsh: error"; else msg="$1"; fi + echo-red "dsh: $msg" + exit 1 + fi +} + +#-------------------------- Installation -------------------------------- + +if [ -r /etc/lsb-release ]; then + lsb_dist="$(. /etc/lsb-release && echo "$DISTRIB_ID")" + lsb_release="$(. /etc/lsb-release && echo "$DISTRIB_RELEASE")" +fi + +if [[ $lsb_dist != 'Ubuntu' || $lsb_release < '14.04' ]]; then + echo-red "Sorry, this script only supports Ubuntu 14.04+" + exit 1 +fi + +echo-green "Installing Docker..." +curl -sSL https://get.docker.com/ | sh && \ +sudo usermod -aG docker $(whoami) && \ +sudo docker version +if_failed "Docker installation/upgrade failed." + +echo-green "Installing Docker Compose..." +sudo curl -L https://github.com/docker/compose/releases/download/$DOCKER_COMPOSE_VERSION/docker-compose-`uname -s`-`uname -m` -o /usr/local/bin/docker-compose && \ +sudo chmod +x /usr/local/bin/docker-compose && \ +docker-compose --version +if_failed "Docker Compose installation/upgrade failed." + +echo-green "Adding a subnet for DockerBox..." +ip_mask="192.168.10.1/24" +# Make sure we don't do this twice +if ! grep -q $ip_mask /etc/network/interfaces; then + cat > /tmp/dockerbox.ip.addr <