Ariadne is in active development at Myplanet Digital, and should be considered beta code. Although we dogfood the project, stability and full documentation not yet guaranteed.
Remember, Ariadne, you are the dreamer, you build this world. I am the subject, my mind populates it.
-- Cobb, Inception
Ariadne is a standardized virtual machine (VM) development environment for easily developing Drupal sites in a local sandbox that is essentially identical to a fully-configured hosted solution. Once several simple system requirements have been met, it can be set up using only a few commands from your computer's terminal.
It attempts to emulate Acquia's infrastructure as closely as possible (with added development tools), using Chef cookbooks and roles that can easily be used to deploy an actual cluster.
Ariadne has been tested on Mac OS/X Snow Leopard & Lion and Ubuntu 12.04 (and it should work on other flavours of Linux). Theoretically, it should support Windows as well, although Ariadne has not been tested on it.
How It Works
Ariadne is a customized implementation of Vagrant. Vagrant uses Virtualbox to boot a stripped-down virtual machine image, and then uses the Chef configuration management tool (one of the few components installed on the VM initially) to bring that blank slate into a fully configured state.
The guest virtual machine is configured identically, regardless of the host computer's operating system and configuration.
Recommended versions in parentheses.
- Virtualbox (4.1.23)
Ruby version manager (RVM) (1.16.7)
curl -L get.rvm.io | bash -s 1.16.7 # Install/Update RVM exec $SHELL # Relaunch shell
On OS/X: Xcode or Command Line Tools for Xcode
apt-get install build-essential libreadline5 libssl-dev nfs-kernel-server
Ubuntu > 12.04:
apt-get install libreadline-gplv2-dev
Ubuntu <= 11.04:
apt-get install libreadline5-dev
Quick and Dirty Start
First install Vagrant v1.0.6 DMG from the project homepage:
Then run these commands:
$ vagrant gem install vagrant-vbguest vagrant-hostmaster vagrant-librarian $ [sudo] gem install librarian rake knife-solo
Run these commands to set up Ariadne:
$ git clone https://github.com/myplanetdigital/vagrant-ariadne.git $ cd vagrant-ariadne
If you have RVM installed, the
.rvmrc script will now run and ensure you
have the right version of ruby. Otherwise, you can simply use the system
Next, run the setup command with:
$ rake setup
This is a non-destructive command that will download the correctly versioned rubygem packages and Chef cookbooks, among other things. You should run this command any time you upgrade or downgrade Ariadne.
You're now set up and ready to boot a machine. This can be either the simple example site (included with Ariadne), or a full-fledged Ariadne project.
Booting the example
If you'd like to spin up the demo site (currently a simple Drupal install on a basic virtual machine), just run this command:
$ vagrant up
This command will take a while to finish the first time you run it, because Vagrant must download the disk image for the guest operating system (which can be several hundred megabytes in size), and set up the virtual machine's hard-drive for the first time (which involves downloading and installing any required software to the guest machine).
When it's done, you can visit http://example.dev/ to view the example website!
Booting an Ariadne project
If you already have an Ariadne project (basically a Chef cookbook), you can boot that instead of the demo.
Either place the Ariadne project in the
cookbooks-projects folder, or run
$ rake "init_project[GITURL]" # don't forget the quotes!
to clone the project at the specified Git URL into the
correct directory for you. Note that for your typing convenience, it will
remove the prefix
ariadne- from the directory name if it exists.
Once the project is in place, run
$ project=PROJECTNAME vagrant up
to spin up the project. The
project=PROJECTNAME tells Chef which
cookbooks-projects to use for the final provisioning
Your site will be available at http://PROJECTNAME.dev/ when it is done.
After the demo or project-specific VM has spun up, here are several commands that might be useful:
$ rake send_gitconfig # Send your personal gitconfig to the virtual machine. $ vagrant ssh-config >> ~/.ssh/config # Adds an entry to your ssh config.
At the end of the day
To shut down the virtual machine, run:
$ vagrant halt
Later, you can run
vagrant up to start the virtual machine again. This time,
setup will be quite fast because the virtual machine has already been set up.
If you want to rebuild the virtual machine from scratch (which you'll want to do from time to time, to ensure you haven't introduced any invisible dependencies), you can run:
$ vagrant destroy
to delete the virtual hard disk (it won't delete the folder shared between your
computer and the virtual one). Next time you run
vagrant up, Vagrant will
set up the virtual machine from scratch.
As mentioned, an Ariadne project is just a Chef cookbook to take the VM through
the last mile of project-specific configuration. An example of an Ariadne
project cookbook is available in the
cookbooks-projects/example folder of this
project. It's the project used to set up the demo site. For simple Drupal
projects, you could copy the example folder and use it as a basis for your own
Ariadne can theoretically be used to provision a remote dedicated server using the knife-solo tool. This does not yet work.
(Feel free to use these instructions to deploy a fresh Rackspace cloud server.)
Pending deploy instructions:
export ARIADNE_PROJECT=myproject export REMOTE_IP=126.96.36.199 echo -e "\nHost $ARIADNE_PROJECT\n User root\n HostName $REMOTE_IP" >> ~/.ssh/config ssh-forever $ARIADNE_PROJECT -i path/to/ssh_key.pub # Enter root password when prompted. # Install Chef on the server knife prepare $ARIADNE_PROJECT --omnibus-version 10.16.6-1 # Run chef-solo on remote server knife cook $ARIADNE_PROJECT nodes/dna.json --skip-syntax-check --skip-chef-check
Goals and Features
- You can use your preferred tools (text editor, database browser, etc.) to work on the website.
- When you make a change, it should be immediately observable in your browser.
- Certain caches are stored in the persistant directory shared between the host and guest machines, making it faster to rebuild from scratch.
- Installs tools automatically:
- Advanced performance tools: Varnish, Memcache, and APC.
- Percona, the drop-in MySQL replacement used by enterprise Drupal hosting providers.
- Debugging tools: xhprof, xdebug, webgrind.
- Except for the debugging tools, Ariadne strives to implement as little Vagrant-specific server configuration as possible (i.e.: strive to be as "production-like" as possible).
- E-mails sent by PHP will be forwarded to the nearest mail server, meaning you (and potentially, your clients) will recieve e-mails from the virtual machine.
- DNS resolution from inside the VM, even when connecting to endpoints through VPN.
Differences from vanilla Vagrant
Incredibly standardized environment: We've tried to lock everything down
as much as possible, to ensure that when one user encounters an issue, we all
encounter it together. Here are the tools we used:
- A recommended version of Virtualbox to boot the virtual machines.
- Standard baseboxes reliably built with Veewee (an automated basebox-building tool).
- Ruby Version Manager (RVM) to ensure Vagrant runs on a specific ruby version.
- Bundler to ensure Vagrant and our host-machine tools run on specific gem package versions.
- Librarian to ensure specific versions of Chef cookbooks are used, which in turn ensures identical VM configuration.
- SSH agent forwarding: Your host machine's SSH session is forwarded into the VM, so when you SSH in or run Chef, the system will have all the same access that you have on your host machine. In other words, you can clone the same private git repositories or SSH into the same remote machines from your VMs as you can on your host machine.
Persistent apt cache: Every time Vagrant provisions a machine, the VM must
re-download all the software packages using the apt package manager. Normally
the VM caches all the downloaded files in a special directory, but this
directory is lost whenever a VM is destroyed and rebuilt. For this reason, we
share the directory in
tmp/apt/cache, so it will persist between VM builds.
vagrant-hostmaster host file management:
automatically manages your systems
/etc/hostsfile based on settings in
Upgrading or debugging Ariadne itself
If you pull changes or switch branches in the Ariadne repository, you'll very
likely need to rerun the setup. At the very least, you should exit and re-enter
the vagrant-ariadne directory so that RVM will rerun the
.rvmrc script (where some
setup happens). You should then run
rake setup again.
- Ensure you are using a basebox with the same architecture as your system. In
other words, running the lucid64 basebox on a 32-bit system is NOT going to
This can be a problem for Snow Leopard users in some cases, because some
models of 64-bit Macbooks will boot into 32-bit mode by default when running.
Snow Leopard. Please run
uname -mand check that the system architecture matches your basebox (
i386= 32-bit). This Apple knowledgebase article should help you configure your machine correctly if it's not already.
- The standard MySQL port
3306inside the VM has been forwarded to port
9306on the local machine. This was done to avoid conflicts on systems where
3306is already in use by MySQL on the local machine. When the VM is booted, you may connect your MySQL GUI to port
9306to access the VM's MySQL directly.
- Several baseboxes that are presumed to work for Ariadne are available for use:
lucid64. (More may be added to
config/baseboxes.ymlin the future.)
- Ariadne uses agent forwarding to forward the host machine's ssh session into the VM, including keys and passphrases stored by ssh-agent. What this means is that your VM will have the same Git/SSH access that you enjoy on your local machine.
Tips and tricks
- Several configuration settings can be tweaked in the
cpu_count. Alternatively, any one of these can also be set on the command line while running vagrant commands, and the values will be written into
config.yml. For example:
memory=2000 cpu_count=4 vagrant reloadwill reload the VM using 4 cores and with 2GB of RAM.
- These is a special environment variable that can be set for use during any
vagrant command that results in a chef run:
clean=true vagrant provision. It is up the each external ariadne project cookbook to implement this feature, but the intention is that it makes it simpler to wipe out any data directories needed to rebuild the site. For example,
vagrant provisionwill not run
drush site-installwhen it detects that the docroot is already present, but setting the
clean=truevariable can tell chef to delete the docroot, and so the site will be rebuilt as it was during the first chef run.
If your project's individual ariadne cookbook (for last-mile configuration) has implemented it, you can specify the branch of your project to build:
branch=123-story-description clean=true vagrant provision
Keep in mind that the
branchflag might not have any effect in some cases, such as the default
The chef roles installed in the VM are partially configurable via
config.ymlor the command-line. Any role in the
roles/directory can be used to build the environment. We are working to allow any reasonable combination of roles, but this is still a work in progress. Order of roles will affect success of a build. These are valid ways to build Ariadne:
roles=acquia,dev_tools vagrant up # DEFAULT roles=apache2_mod_php,memcache,mysql,drupal vagrant up # NO VARNISH
- Having dnsmasq installed on the host computer can lead to unexpected behavior
resolv.confin the VM. This will manifest as a failure to upgrade chef (via rubygems) during boot, right off the bat.
cding into non-root of project directory (for example, typing
$ cd vagrant-ariadne/data), RVM will create new directories relative to that directory!. See notes in the
.rvmrcfor info on why normal bash script approach is avoided.
- It seems that some network connections (especially ones from Rogers Telecom)
will result in misconfigurations of
/etc/resolv.confin the VM. If your VM is unable to download packages or run
apt-get update, please compare the
/etc/resolv.confof the VM with that on your host computer (which presumeably works fine). Copy the relevant bits from your host machine. We're working on sorting out the origins of this.
Ariadne has been tested with a lucid64 basebox that was built on 2012-05-07T21:00:04Z. Please consider downloading a newer build if yours is out of date. To see when your basebox was built, run this command:
$ sed -n 's/.*lastStateChange="\(.*\)".*/\1/p' ~/.vagrant.d/boxes/lucid64/box.ovf
LogMeIn Hamachi is known to cause issues with making
pear.php.netunreachable, and so the environment won't build.
Sometimes you might get an error like this while running
The VM failed to remain in the "running" state while attempting to boot. This is normally caused by a misconfiguration or host system incompatibilities. Please open the VirtualBox GUI and attempt to boot the virtual machine manually to get a more informative error message.
Should this occur, running
vagrant reloadmay work, but we recommend that you restart your system.
- If vagrant seems to freeze at "Waiting for VM to boot", try aborting (CTRL-C)
vagrant reload. This will usually go away after a system restart.
Please refer to https://github.com/myplanetdigital/vagrant-ariadne/issues?labels=bug&state=open for a full list of bugs.
- Create sister project to provide a base install profile that is pre-configured to use the advanced components (Memcache, Varnish, etc.) In progress: 2ndleveldeep
- Either avoid using the confusing word "host" (vs "guest" VM) to describe local machine, or define terminology somewhere.
- Add proper string support using
- Convert to rubygem?
- Convert example project to use
drush qd --no-server.
License and Author
Copyright: 2012, Myplanet Digital, Inc.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.