A Vagrant VirtualBox which contains pre-installed Docker Engine CE, Docker Compose, Docker Machine, and AWS CLI software.
This Vagrant VirtualBox is useful for quick testing of miscellaneous Docker-related experiments, or software evaluation. Because the Docker Machine and AWS CLI software is installed, it also supports deployment of Docker containers from this Vagrant VirtualBox (vagrantbox) to any Amazon Web Service Region, (AWS), via the AWS CLI.
This Vagrant box should work on any host computer which has Vagrant and VirtualBox installed, but it has been tested only on Ubuntu 14.04 and Ubuntu 16.04.
This Vagrant VirtualBox is easy to install, assuming you already have Vagrant and VirtualBox installed. Because it is a Vagrant VirtualBox, it is also easy to remove; simply use the vagrant destroy command, and the trash has been taken out.
I use this Vagrant box for development and testing of my GitHub project php-server-mon-sys :
https://github.com/addiscent/php-server-mon-sys
- Internet connection
- Hardware virtualizable CPU, (vagrant-docker-aws is a 64-bit guest)
- 600MB available memory is the default. You may reduce or increase
- 2GB available disk storage
- Vagrant 1.9.3, (https://www.vagrantup.com/)
- VirtualBox 5.1.14, (https://www.virtualbox.org/)
- UnZip 6.00, (or equivalent alternate)
Bringing up this vagrantbox typically takes less than ten minutes. The time required will vary, depending on the speed of your host and Internet connection.
Open a terminal bash session on your host.
Make a project directory and set it as the current directory, e.g. :
$ mkdir ~/vda-test
$ cd ~/vda-test
Download the vagrant-docker-aws project ZIP file, named master.zip, and then uncompress-unarchive the files from it into your work directory. The unzip command automatically creates a subdirectory named vagrant-docker-aws-master. Set that directory as the current working directory :
$ wget -O vagrant-docker-aws.zip https://github.com/addiscent/vagrant-docker-aws/archive/master.zip
$ unzip vagrant-docker-aws.zip
$ cd ~/vda-test/vagrant-docker-aws-master
$ ls -al # list the vagrant-docker-aws project files
-rw-rw-r-- 1 usr grp 3.9K Jun 9 05:46 bashrc-mod.txt
-rw-rw-r-- 1 usr grp 13 Jun 9 05:46 .gitignore
-rw-rw-r-- 1 usr grp 12K Jun 9 05:46 LICENSE
-rw-rw-r-- 1 usr grp 3.5K Jun 9 05:46 README.md
-rw-rw-r-- 1 usr grp 4.5K Jun 9 05:46 Vagrantfile
Note that you may rename the vagrant-docker-aws-master directory, if you wish. If you suspect you may rename it sometime in the future, it is best to do so now.
Use the vagrant up command to create a new vagrantbox. During creation, the Vagrantfile provisioning script installs Docker suite and Amazon Web Services Command Line software, (AWS CLI) :
$ vagrant up
Most of the time required for creation of the vagrantbox is consumed by the one-time-only task of downloading the bento/ubuntu-16.04 image from hashicorp.com, and also by the one-time-only installation of the Docker suite and AWS CLI.
When the vagrant up command is used to resume the halted vagrantbox the second time or thereafter, it will load and finish startup in approximately one minute or less.
During creation of the vagrantbox, a substantial amount of text is output to the host terminal. On a terminal with color output enabled, much of the text is green and red. This is normal. Vagrant has finished creating the new vagrantbox when one of the last lines of text output shows something similar to :
==> ++ sed -i 's/localhost/localhost vbox-docker-aws/' /etc/hosts
When the terminal prompt returns after the new vagrantbox has been created, start an ssh session with the new vagrantbox :
$ vagrant ssh
In the ssh session created by vagrant ssh, the terminal displays some Ubuntu 16.04 Server login banner info, and the following terminal prompt :
vagrant@vbox-docker-aws:~
$
Note the name of the currrently logged-in user is vagrant. The user vagrant is the user logged in by default on this vagrantbox using "vagrant ssh".
Confirm successful installation of the Docker suite and AWS CLI by entering the following commands and noting the appropriate results:
$ docker --version
Docker version 17.03.1-ce, build c6d412e
$ docker-compose --version
docker-compose version 1.11.2, build dfed245
$ docker-machine --version
docker-machine version 0.10.0, build 76ed2a6
$ aws --version
aws-cli/1.11.68 Python/3.5.2
Note that the provisioning script in the Vagrantfile always attempts to install the most recent release of Docker suite and AWS CLI, so the version numbers you see may be newer than those listed above.
You may need to know the following credentials for some admin activities in this vagrantbox :
user : vagrant
password : vagrant
Docker installation, including addition of the user vagrant to the group docker, is performed by the provisioning script of the Vagrantfile, during vagrant up. If Docker-related configuration did not complete properly during provisioning, errors occur when attempting to execute Docker commands. The following "pass/fail" test verifies the configuration is correct for the current user, (in this case, vagrant).
$ docker run hello-world
Unable to find image 'hello-world:latest' locally
.
.
Hello from Docker.
.
.
For more examples and ideas, visit:
https://docs.docker.com/engine/userguide/
If Docker is not configured correctly, or if the user vagrant has not been added to the docker group as required, an obvious error message is displayed. There should be no error message, in this case.
Note the message above shows "Unable to find image 'hello-world:latest' locally". This is normal, because "hello-world" has never been run as a Docker container before on this vagrantbox. When Docker can't find an image locally, Docker's next step is to attempt to download it from the Docker Hub repository named library/hello, (https://hub.docker.com). The message above also contains the phrase, "Hello from Docker". This is another sign that Docker is configured and functioning correctly.
The OS of the newly created vagrantbox is Ubuntu 16.04 Server 16.04. Explore it in whatever manner you wish, it's simply yet another Linux host, which happens to already have Docker and AWS CLI commands installed. Try things you would never feel comfortable doing on a host which in the past took two hours, (or two days), to install and configure. It's not sacred, it's discardable; if you corrupt it, you may vagrant destroy it, (see Uninstallation below), and recreate a new instance of it just as before, in less than ten minutes.
When you are finished exploring and ready to shut down the vagrantbox, exit the vagrant ssh session and return to your host terminal prompt using the usual method :
$ exit
logout
Connection to 127.0.0.1 closed.
The vagrant destroy command removes the vagrantbox instance files, (including the sysroot volume of the Ubuntu 16.04 Server 16.04 vagrantbox itself), from storage on the host. Any changes previously made to this particular vagrantbox configuration, (e.g., by using a vagrant ssh session to do work such as editing/creating files on the vagrantbox sysroot volume), will be destroyed along with the vagrantbox.
The vagrant destroy command does not delete the vagrant-docker-aws-master work/project directory, nor any of the files in that directory :
$ cd ~/vda-test/vagrant-docker-aws-master
$ vagrant destroy
default: Are you sure you want to destroy the 'default' VM? [y/N] y
==> default: Forcing shutdown of VM...
==> default: Destroying VM and associated drives...
$ ls -al
-rw-rw-r-- 1 usr grp 3.9K Jun 9 05:46 bashrc-mod.txt
-rw-rw-r-- 1 usr grp 13 Jun 9 05:46 .gitignore
-rw-rw-r-- 1 usr grp 12K Jun 9 05:46 LICENSE
-rw-rw-r-- 1 usr grp 3.5K Jun 9 05:46 README.md
drwxrwxr-x 1 usr grp 4096 Mar 9 05:50 .vagrant
-rw-rw-r-- 1 usr grp 4.5K Jun 9 05:46 Vagrantfile
After using the vagrant destroy command, you may then delete from the host the vagrant-docker-aws-master directory, or selected files.
Note: Do not delete the files in the project home directory before executing the vagrant destroy command. The vagrant destroy command is dependent upon reading the Vagrant-specific files in the project directory; the vagrant destroy cannot function without those files. If the vagrant destroy command cannot be executed, orphaned VirtualBox instance files will accumulate in your VirtualBox VM storage directory. They cause no harm, but may consume large amounts of unnecessary space on host storage. If you prevent the execution of vagrant destroy by inadvertently deleting the Vagrant files, you may delete orphaned VirtualBoxes using the VirtualBox GUI or VirtualBox CLI commands.
The most important of the commonly used commands are :
vagrant help
vagrant up
vagrant status
vagrant global-status
vagrant port
vagrant suspend
vagrant resume
vagrant halt
vagrant destroy
vagrant box
The default VagrantBox memory allocation is 512MB, which may be increased or reduced by revising the Vagrantfile. To do so, revise this Vagrantfile directive :
vb.memory = "512"
Change from 512 to, e.g., 256, or 1024, etc. Take care to not exceed the host's amount of available memory.
After revising that directive in the Vagrantfile, reload the vagrantbox by executing the following command :
$ vagrant reload
If you wish to run a server or app inside vagrantbox which does port IO, such as an NGINX server or a Rails thin web-server, you must configure Port Forwarding on vagrantbox. For a complete discussion, see Vagrant's documentation about Port Forwarding : https://www.vagrantup.com/docs/networking/forwarded_ports.html
To support php-server-mon-sys project, (https://github.com/addiscent), the Vagrantfile contains a directive which forwards port 28684 on the vagrantbox to port 28684 on the host.
If port forwarding is required for your project, the following Vagrantfile directive is used to configure it. If port forwarding is not needed for your project, you may remove the directive, by either "commenting it out", or deleting it.
If necessary, change port mapping by revising the Vagrantfile, editing the following directive as needed:
config.vm.network "forwarded_port", guest: 28684, host: 28684
As an example, to change the PSMS application service port on the host, (HTTP port), from 28684 to 8888, revise the directive as :
config.vm.network "forwarded_port", guest: 28684, host: 8888
After revising that directive in the Vagrantfile, reload the vagrantbox by executing the following command :
$ vagrant reload
As installed above, this vagrantbox can be a useful tool, but it has the potential to do much more.
In order to take full advantage of a vagrantbox it is neccesary to learn the Vagrant way of using it on a host. It's possible to do some really interesting work with Vagrant/VirtualBox instances, but, to do advanced work it is necessary to learn vagrant command line usage, (such as listed above). It is also necessary to become familiar with the Vagrantfile directives; the Vagrantfile directives noted above are just a few of the many available.
For more information, read the official Vagrant documentation : https://www.vagrantup.com/docs/
In addition to being a provider for Vagrant, VirtualBox is very valuable even when used by itself : https://www.virtualbox.org/manual/UserManual.html
There exists a vagrantbox configuration option which allows a file-system directory to be "shared" between the host and a vagrantbox. This allows both the host and the vagrantbox to operate on the same directories and files, (read, write, etc). As an example, a software developer may edit web page source files on the host, and a vagrantbox HTTP server may deliver them. This technique is used on the vagrant-ruby-rails project, (https://github.com/addiscent/vagrant-ruby-rails). For more information, refer to the Vagrantfile directive named "config.vm.synced_folder", in the Vagrant documentation.
If there is no active "config.vm.synced_folder" directive in the Vagrantfile, Vagrant will by default share the directory of the host which contains the vagrantbox, (in our case ~/vda-test/vagrant-docker-aws-master), into a directory of the guest, named "/vagrant". To confirm that this is the case for your installation, list the /vagrant directory while in a session with the guest; it should be exactly the same as the ~/vda-test/vagrant-docker-aws-master listing above :
vagrant@vbox-docker-aws:~
$ ls -al /vagrant
-rw-rw-r-- 1 vagrant vagrant 224 Mar 30 03:17 bashrc-mod.txt
-rw-rw-r-- 1 vagrant vagrant 13 Mar 30 03:17 .gitignore
-rw-rw-r-- 1 vagrant vagrant 11358 Mar 30 03:17 LICENSE
-rw-rw-r-- 1 vagrant vagrant 15573 Mar 30 03:17 README.md
drwxrwxr-x 1 vagrant vagrant 4096 Mar 30 03:20 .vagrant
-rw-rw-r-- 1 vagrant vagrant 4516 Mar 30 03:17 Vagrantfile
The Vagrantfile may also be used to do non-trivial configuration of the OS on the vagrantbox during its initial creation, a process known as Provisioning.
In order to save yourself time and effort, try to make it a habit to not laboriously create a "pet" vagrantbox instance which is configured by manually installing more "infrastructure" software after it is initially created. Instead, modify the Vagrantfile with directives and script commands. By doing so, after executing vagrant up the first time, the vagrantbox is already configured the way you need it.
Vagrant-docker-aws provisioning is performed by an inline script, at the end of the Vagrantfile. You may customize the provisioning as needed by editing that section. An example of what you may wish to include in the provisioning script is the installation of Git, (hint: add "apt-get -y install git" at the end of the inline script in the Vagrantfile).
If you create your own new types of vagrantboxes, you may begin to lose a common fear you had in the past, the fear that you "can't try this or that", because it's too risky and may bork your new carefully hand-modified vagrantbox. So, study the Vagrantfile and related documentation. Experiment with it, customize it to create a vagrantbox which does what you need, from the first vagrant up. Let your mind rest easy, knowing that if you fubar a vagrantbox you are using, you can simply vagrant destroy it, and then quickly "vagrant up" a new one, provisioned according to your need.
Use of the config.vm.network Vagrantfile directive allows for some interesting experimentation with more advanced architectures. If the host has enough CPU muscle and memory, multiple vagrantboxes may be run concurrently. If you have, say, a relatively modern host with enough memory, you can create your own in-host-memory "virtual server cluster". If you are a student of Distributed Computing, Internet, and Cloud technologies, you can learn about Virtual Networks by configuring and running your own networked cluster of servers, all entirely on a single computer, (fair warning: not simple!). It's a very inexpensive way to teach yourself about advanced computing architectures which can be implemented in the "real world", e.g., on AWS, or a company's networked hardware.
Licensed per Apache License version 2.0
Copyright 2017 Rex Addiscentis raddiscentis@addiscent.com