Learn to build and share a ready-to-rock GNU/Linux virtual machine image with
your team, including a complete graphical development
environment, all necessary packages, and a preloaded, running "starter" web
application, accessible from a browser in the host OS.
Once the VM is provisioned running, you can access a sample static web site from the "host" OS on localhost:9980 as well as a JavaScript-based to-do list application (based on TodoMVC) on locahost:9981.
The former (cloned from this repo)
demonstrates how a remote repository may be cloned using Git
during the Ansible "provisioning" process. The latter demonstrates how you
might serve web content from the cloned repository on the host OS, using
Vagrant's config.vm.synced_folder directive (see
Vagrantfile around line 49). This allows you to do your
development work from the host OS, using your favorite editor, or create
a self-contained and self-hosted repository for showing off your project.
For instructions for accessing the VM over SSH, see the
"Authentication" section, below. For technical details on
the VM provisioning setup, please see TECHNICAL.md.
Every OS is going to require at a minimum:
- a UC GitHub Enterprise or GitHub.com account
- VirtualBox - a way to run "virtual machines"
- Vagrant - a way to automate the creation/setup of VMs
If you already know how to clone a repository from GitHub, then clone this
repository (web-dev-with-friends) to your computer and following the steps
below.
Once the base VM image is downloaded and all the provisioning steps are completed (takes less than ten minutes on campus wifi), you will be able to access one of the sample web sites at localhost:9980 or :9981 from the "host" operating system.
On Windows:
- Install (at a minimum) VirtualBox and Vagrant, as noted above
- Open a command prompt inside the
web-dev-with-friendsrespository you just cloned (in Explorer, you can Shift+right click on the directory and pick "Open command window here"; screenshot) - type in
setup.cmdand press ENTER- if you get the error "Vagrant could not detect VirtualBox!" as described
in this issue, try adding the path to
VBoxManage.exe(probablyC:\Program Files\Oracle\VirtualBox) to your%PATH%(how-to)
- if you get the error "Vagrant could not detect VirtualBox!" as described
in this issue, try adding the path to
- visit localhost:9980 in a web browser on the host OS
On Unix-like operating systems (macOS / Linux):
- Install (at a minimum) VirtualBox and Vagrant, as noted above
- Inside a terminal,
cdto where you cloned theweb-dev-with-friendsrepository - run
./setup.shto start the installation - visit localhost:9980 in a web browser on the host OS
macOS (the OS formerly known as OS X) and most GNU/Linux distros will already
have Git install installed. However, if you get an error on Linux when you type
git at the command line, then install git (possibly git-core) from the
distro's package manager.
It's sufficient to run setup.cmd in Windows' built-in Command Prompt, but in
order to work most productively with the VM image created by this repository,
you'll want a "genuine" Unix shell that provides the OpenSSH ssh
binary.
Learning how to use the Unix shell (e.g., Bash) is beyond the scope of this workshop, but you can find some resources here.
The easiest way to get started is by by installing the GitHub GUI, which can be easily configured to provide a Bash shell you can use to connect to the running VM.
Once installed, change the GitHub GUI settings as shown below:
Then browse to this repository (web-dev-with-friends)
on github.com or on github.uc.edu and click the
"Clone or download" button, followed by "Open in Desktop":
After that, you can right click on the repository in the left panel of the GitHub GUI, and choose "Open in Git Shell." This gets you a real Unix-type shell, and at that point you can basically follow any of the Unixy instructions above.
If you do any Git commands in this shell though (say, git pull), you'll have
to input your GitHub credentials, which is bad for lazy people, so it might
help to study up on SSH public-key authentication and ssh-agent
(guide).
With the Mac operating system (formerly known as OS X or Mac OS X), you already have all the software you need to clone the repository from the command line. Search using Spotlight (⌘ + space) for "terminal" if you don't know where Terminal.app is found.
You might still prefer starting with the GitHub GUI for Mac, and
that's fine. If you use the GitHub GUI on Mac, you can follow the same basic
steps as for Windows, above, to clone the web-dev-with-friends repo from the
web. You don't need to configure the "Git Bash" shell, because macOS is a Unix
operating system, and already comes with the Bash shell.
Installation packages for Vagrant and VirtualBox are, however, still required on a Mac; see above for links to the main project sites.
On GNU/Linux, you'll want to at a minimum install the git-core or git
[package] from your OS's package manager. git-cola or gitg
would be good choices if you'd like a GUI.
Then, just paste these commands
cd ~/path/to/your/dev/stuff
git clone git@github.com:QuickFixes/web-dev-with-friends.git
cd web-dev-with-friends
./setup.sh
into a terminal, replacing git@github.com with git@github.uc.edu if you are
a UC student and don't have a GitHub.com account (since this repository exists
in both places).
Precompiled packages for both Vagrant and VirtualBox should exist in some form
in the "contrib" or "universe" repositories of your Linux distribution. As of
this writing, however, it's best to use the installation instructions on the
main project site (installing with pip), because you'll run into
problems with some of the older versions. (Give them a few years to sort out
these kinks, it's a relatively young project.)
You will connect to the running virtual machine over SSH as the user
vagrant. This user is in the sudoers file (by way of being a
member of the group sudo), which means it can become the superuser (root)
with no password.
The Vagrant user's default password is vagrant.
If you have any problems with authentication, please refer to
TECHNICAL.md.
In order to connect with the VM over SSH, normally you would just type
vagrant ssh inside the "root" of this repository, wherever you originally
cloned it.
You'll find additional advice about connecting over SSH (including using SFTP
programs like Cyberduck) in TECHNICAL.md.
Oh, you did? Well, an error message to the effect of "Run `vagrant init` to
create a new Vagrant environment" usually means that you were in a subdirectory
and forgot to cd into the top level of the repository (where the
Vagrantfile lives) before running vagrant up or vagrant ssh.
The vagrant command expects to be run in the same working directory as where
the Vagrantfile lives, so that it can read the
configuration directives for the VM before attempting to
start/provision/connect to it.
Out of the box, Windows lacks the OpenSSH ssh binary which Vagrant expects to
find in your PATH when you vagrant ssh, so you would need to run this
command inside of a Bash (or Cygwin) shell, which the GitHub GUI for
Windows provides. (Provided you correctly followed the instructions above.)
You can always use PuTTY and just connect to localhost port 9922, but then you have to type a username and password ("vagrant" for both), which is bad for lazy people. Setting up PuTTY profile to auto-type the username and use Vagrant's private key is an option, but beyond the scope of these instructions.
The Vagrantfile will automatically create the following
forwarded ports for you.
| Guest (VM) port forwards to... | Host port # | Notes |
|---|---|---|
| 22 | 9922 | Secure Shell (see above) |
| 80 | 9980 | Apache HTTP server |
| 81 | 9981 | Apache HTTP server |
| 5000 | 55000 | Python / Flask app |
It was after some deliberation that I decided to stick with 55000 for a Flask server (not included in this repo, but try this), so that it wouldn't interfere with the default configuration of a local Flask server you might be experimenting with. Just make a bookmark to http://localhost:55000 and remember that it goes with the Flask app running on the VM.
Probably not, unless you have a specific need to share a standardized GNU/Linux development / server environment with a team of people, with the entirety of the VM's configuration stored in version control.
If you've never done it before, you could actually learn a lot just doing it the "manual" way: downloading the installation ISO for a GNU/Linux distribution and installing it in a new VM (here's a how-to for Ubuntu).
You don't need to clone this repository to do that, and you certainly don't need (or want) Vagrant getting in the way if you're trying to learn how to create a Linux VM from scratch. Vagrant is an advanced tool, and Ansible is an even more advanced tool. You might need them someday, but maybe that day isn't here yet.
That said, what the contents of this repository do give you is a fully-configured Debian Jessie VM with a working Apache server, a good Vim development environment with lots of fancy plugins, and a couple of sample web applications, all spun up on demand from a set of well-commented "recipes" (e.g., the
Vagrantfileand the contents of theprovisioningsubdirectory) which you can use as the basis for your own team project.
Yes, what about Windows, indeed.
That's part of the reason why this repository exists: to give your team a consistent working environment, independent of their "preferred" OS.
However, since Windows lacks a sensible built-in command line and most of the tools necessary to do "full-stack" web development using open source technologies, you need a mishmash of software to fill in the gaps.
Graphical Git clients such as the official GitHub GUI (Mac version) and SourceTree help alleviate some of the pain of setting this all up, by bundling a functional Unix shell. The virtual machine you'll get after running the setup script in this repository is designed to provide everything you need to get started with PHP or Python web development on the Apache HTTP server.
It's not.
But it saves you from having to distribute a potentially very large VM image to your team, which you have spent hours of your life custom crafting for one GNU/Linux distribution's release, with one specific purpose in mind.
By putting these instructions in configuration files (which can be version-controlled with Git), you can build similar virtual machines for different projects with slightly different requirements without duplicating all that effort.
It's not.
But it saves you from having to manually install a dozen different software packages, copy default configuration files, deployment SSH keys, or whatever else, over and over and over again, for each new project.
Using Ansible allows you to record these steps in a mostly-human-readable YAML configuration file, which you can just clone and modify for your next project.
These configuration files are like having really comprehensive, version-controlled notes on everything you did to set up your development / hosting environment, and they can even be lightly modified to apply the same steps to a cloud-based host (Amazon AWS or a similar competitor).
It's not.
But it provides you with a complete blueprint of how to set up the "base box" for a virtual machine development environment for your team—beginning from the distro's installation ISO. Which you can then check into version control.
This could come in handy if the Vagrant
.boximage (that you spent hours of your life getting just right) became corrupted, or was otherwise lost through some data storage disaster.There is no requirement for anyone on your team to perform the steps discussed in
TECHNICAL.mdto rebuild the base box, but it saves you time when you make a clone of this repository for your next project.Keep in mind, too, that this repository is a just a few hundred kilobytes (if you don't count the slides). If your team is patient and doesn't mind downloading a 4.7 GB installation ISO, you actually don't even have to host the Vagrant "base box" anywhere on the 'net.
- Incorporates the "VanillaJS" example from the TodoMVC project at revision 635fd9f