Giters

wunc / localvm

local Vagrant environment created from Puphpet

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

ORIS Development Environment

Introduction

A common problem in website development is working with code created and edited in different environments by team-members. If you want to invite a new developer to work on a project, it is often a hassle getting them all of the necessary tools that the project requires.

This project provides a solution: a virtual machine that provides a common pre-configured development environment with all of the tools necessary for working on projects in the UTD ORIS team.

Features

  • LAMP (Linux, Apache, MySQL, PHP)
  • Dependency Managers (composer, npm, bower)
  • Others (git, gulp, xdebug, wp-cli, ruby, sass, capistrano, mailcatcher)

Requirements

Installation

  • Install the requirements listed above
  • Put any websites that you want hosted into ~/Sites. These will automatically be mapped to /var/www in the VM (using 2-way NFS)
  • Install the environment
mkdir Vagrant
cd Vagrant
git clone git@github.com:wunc/localvm.git localvm
  • Configure as needed
    • modify or add components: All of the configuration is set in one file: puphpet/config.yaml. One thing you may want to change: find the chosen_provider and set it appropriately (either to vmware_fusion or virtualbox).
    • customize your environment: If you want to change any dot-files, they are located in puphpet/files/dot; edit them prior to starting the vm and they will be copied over to the vm on boot. If you want to override any of the default settings, create a file called puphpet/config-custom.yaml. Use the same style as the default config.yaml and change (or add) the desired setting.
  • Load the environment
cd localvm
vagrant up

The last command will take a while to complete (the first time you run it), as it has to download the image, install it, run it, and install all of the included software.

+++++++++++++

NOTE:

  • If you experience errors with 'vagrant up' under VMWare Fusion, there are a couple things to check.

    • Check that the file '/Library/Preferences/VMWare\ Fusion/networking' exists.
      • If not, issue sudo touch /Library/Preferences/VMWare\ Fusion/networking in the terminal.
    • VMWare Fusion also tries to install a Kernel Extension on the Mac but may not display an error if it's unsuccessful.
      • Open System Preferences -> Security & Privacy -> General
        • If an error is displayed, click Allow to fix the error
    • Then go back to the localvm directory and issue 'vagrant up'

+++++++++++++

  • Edit your hosts file:
sudo nano /etc/hosts
  • Add the following to the bottom of your hosts file:
192.168.57.101	local.test
192.168.57.101  www.local.test
192.168.57.101  localvm.test

along with any other *.test domains that you would like to set up

Usage

  • Local editing:
    • put your websites in subfolders of ~/Sites.
    • any local edits to files in that directory will quickly auto-sync to the VM.
    • example: you might create ~/Sites/wordpress. You can then access it at http://local.test/wordpress.
  • Vagrant commands (must be run while in the localvm folder)
    • vagrant up # start the VM
    • vagrant halt # shut down the VM
    • vagrant ssh # ssh into the VM
    • vagrant suspend # suspend the VM
    • vagrant resume # resume a suspended VM
    • vagrant provision # read the config.yaml file and apply any changes to the VM
  • Web server:
  • MySQL server:
    • mysql username: root, password: 123
    • extra mysql username: dbuser, password: 123
    • Sequel Pro or MySQL Workbench: use SSH tunnel to SSH Host 192.168.57.101 with username vagrant and ssh-key Vagrant/localvm/puphpet/files/dot/ssh/id_rsa. MySQL Host 127.0.0.1 with username root and password 123.
  • Adminer (replaces PHPMyAdmin; see below)
  • MailHog (replaces Mailcatcher)

Optional Nice Stuff

Dynamic Virtualhosts

The Apache web server is configured to accept certain virtual hostname patterns and properly set the VirtualDocumentRoot for them. This way, you don't have to edit the config-custom.yaml and re-provision the VM every time you want to add a new vhost.

  • Bedrock-style WordPress
    • *.wp.test uses /var/www/*/web (~/Sites/*/web on your computer) as its DocumentRoot
  • Laravel
    • *.lvl.test uses /var/www/*/public (~/Sites/*/web on your computer) as its DocumentRoot
  • General
    • *.test uses /var/www/* (~/Sites/* on your computer) as its DocumentRoot

In order for this to work, your computer must have it's DNS set up to also dynamically point to the Vagrant VM. For Macs, you can install dnsmasq via Homebrew:

# Update Homebrew
brew update
# Install dnsmasq
brew install dnsmasq
# Create the dnsmasq.conf file
mkdir -pv $(brew --prefix)/etc/
echo 'address=/.test/192.168.57.101' > $(brew --prefix)/etc/dnsmasq.conf
echo 'listen-address=127.0.0.1' >> $(brew --prefix)/etc/dnsmasq.conf
# Add dnsmasq to the list of DNS resolvers
sudo mkdir -v /etc/resolver
sudo bash -c 'echo "nameserver 127.0.0.1" > /etc/resolver/test'
# Start the dnsmasq service
sudo brew services start dnsmasq

After installation, you will probably have to reboot for it to take effect.

Passwordless Vagrant Up

There are two components that require "sudo" passwords in this vagrant setup: NFS and Vagrant Host Manager. They will often prompt you for your password whenever you do a vagrant up. To bypass this, edit the sodoers file:

sudo visudo

and add the following lines (these are OS X specific, replace <username> with your home folder name):

Cmnd_Alias VAGRANT_HOSTMANAGER_UPDATE = /bin/cp /Users/<username>/.vagrant.d/tmp/hosts.local /etc/hosts
Cmnd_Alias VAGRANT_EXPORTS_ADD = /usr/bin/tee -a /etc/exports
Cmnd_Alias VAGRANT_NFSD = /sbin/nfsd restart
Cmnd_Alias VAGRANT_EXPORTS_REMOVE = /usr/bin/sed -E -e * d -ibak /etc/exports
%admin ALL=(root) NOPASSWD: VAGRANT_EXPORTS_ADD, VAGRANT_NFSD, VAGRANT_EXPORTS_REMOVE, VAGRANT_HOSTMANAGER_UPDATE

You can change %admin to your own username or %staff if you are not a local admin.

Backup Databases

Since the databases are stored within the VM, they will be lost if you destroy the VM. However, localvm has been configured to auto-backup the databases on halt or destroy, as long as you have Vagrant version >= 2.1.0 installed.

With that, whenever you halt or destroy your VM, the databases will be backed up to ~/Sites/vagrant-database-backup.sql.gz on your host computer.

Adminer:

I recommend using a dedicated database tool, like MySQL Workbench or Sequel Pro. The VM does come with Adminer, but it may be overwritten if you are upgrading from a previous version. Adminer is a single PHP file, and therefore is very easy to re-install: just download it (I recommend the English-only MySQL version), save it as ~/Sites/adminer/index.php. Then, you should be able to access it at http://local.test/adminer.

Set the VM system timezone

If your system timezone is incorrect, run the following command to set it

timedatectl set-timezone America/Chicago

Install a nice GUI

There is a free menubar app called Vagrant Manager that will help you manage this dev environment. If you prefer that over the command line, install it from the link.

Auto-update /etc/hosts

The plugin Vagrant Host Manager will automatically update the host machine's /etc/hosts file with the defined Apache vhosts in the guest VM. Nice! In you host machine type:

vagrant plugin install vagrant-hostmanager

SSH-Agent forwarding

The environment is configured to forward your host computer's SSH keys into the VM, so that you can, for example, commit to Github or do Capistrano deployments from within the VM. You need to have your host computer configured properly for this to work, however. To do so, use Github's guide to using SSH agent forwarding.

Note: on macOS 10.12 (Sierra), saved ssh keys are not automatically reloaded into the agent upon reboot. A fix is available here.

Updating

First a note: Try not to make any manual changes to Linux inside your VM. Doing so removes the ability to reusably recreate it should the need arise. Keeping all of your customizations centralized in the config.yaml file is the best practice. Better yet, submit any customizations as a pull request to this repository, so everyone on the team can benefit.

To update to the latest version (from the localvm folder):

git pull
vagrant up # if not already running
vagrant provision

Upgrading from version 1.0

# first backup any databases that you would like to keep!
vagrant destroy # destroy the old VM
git pull # get the latest version
vagrant up # this should also provision because it's a new VM

Happy developing!

About

local Vagrant environment created from Puphpet