Version 2.2 is a legacy release, and these documents are no longer being maintained.

Using Vagrant

This guide will setup a new Oracle VirtualBox virtual machine with AtoM installed on your computer. It works works on most operating systems, including MacOS X, Linux, Windows, FreeBSD and others. If you can install these and have at least 2048Mb RAM to spare you should be good.

Minimum system requirements: 2GB RAM; 8GB disk space


This virtual machine is not intended to be used in production. It targets developers or experienced users willing to try out AtoM using Vagrant. If you want to start using AtoM in production, please refer to the other methods of installations explained under this manual.

Install Vagrant and VirtualBox

  1. Install VirtualBox from (or use your package manager). VirtualBox 4.3 or newer is required.
  2. Install Vagrant from (or use your package manager). Vagrant 1.6 or newer is required. Be aware that Ubuntu 14.04 installs Vagrant 1.4.3, which does not meet the requirements.

Spin it up

  1. using your computer’s command-line interface, create a new directory and open it. The location doesn’t matter, but you’ll need to return to it later - all further command line operations should be run from inside the directory.

    mkdir atom-vagrant && cd atom-vagrant
  2. Initialize the current directory to be a Vagrant environment.

    vagrant init artefactual/atom
  3. Run Vagrant (again, from the same directory where you saved the Vagrantfile).

    vagrant up

    Vagrant will download our custom box and boot it in VirtualBox. The download can take anywhere from a few minutes to an hour or more, depending on the speed of your connection, as the box is considerably big (approx 1.4 GB in size).

Connect to AtoM

Now you should be able to connect to AtoM from your local browser.


The default login details are:

  • Username:
  • Password: demo

Connect to the terminal

Run vagrant ssh from the same directory as where you ran vagrant up. Vagrant will connect you to the correct virtual machine.

The login details are:

  • Username: vagrant
  • Password: vagrant

If you are using Windows, the preferred SSH client is PuTTY.


If you are a developer who requires access to the MySQL database in AtoM’s Vagrant box, here are the credentials:

  • Username: root
  • Password: root

Customize the environment

There are a number of configuration changes that you may want to make if you are planning to use git and submit code to a repository.

  1. Locales customize programs to your language and country. We use en_ES.UTF8 but you can change it. The process is explained in the Locale page of the official Ubuntu wiki.
  2. Ideally, you will also update the system to use your current timezone. See how to change the timezone from the command line in Ubuntu.
  3. Set up your username and email in Git.
  4. Create a new SSH keys to authenticate against a git server like Github. Optionally you can forward your local SSH agent using ForwardAgent, e.g. run vagrant ssh -- -A or vagrant ssh -- -o ForwardAgent=yes instead of just vagrant ssh. Alternatively, you can set config.ssh.forward_agent to true in the local Vagrantfile or the global ~/.vagrant.d/Vagrantfile.

Access the code from your host

We have configured a Samba server in the Vagrant box in order to allow you to access the AtoM directory inside the box.

From your host, you could mount the samba share either using mount.cifs or by adding the following entry in /etc/fstab:

// /home/user/Desktop/atom cifs user=vagrant,passwd=vagrant,iocharset=utf8,sec=ntlm,uid=user,gid=user,noauto,user 0 0

Note that the above example is mounting the network share into /home/user/Desktop/atom, feel free to modify this according to your environment.


There are alternative ways to share files between your host and the virtual box, e.g. Vagrant offers a smart detection system that internally uses NFS, vboxsf or rsync to achieve this. However, we’ve found that the most convenient method for our specific case is to share the files via Samba. We may reconsider this in the future. For further reading about this you may want to visit Comparing Filesystem Performance in Virtual Machines by Mitchell Hashimoto, the creator of Vagrant.

Keeping the environment up to date

You can check if the box you’re using is outdated with vagrant box outdated. This can check if the box in your current Vagrant environment is outdated as well as any other box installed on the system.

Finally, you can update boxes with vagrant box update. This will download and install the new box. This will not magically update running Vagrant environments. If a Vagrant environment is already running, you’ll have to destroy and recreate it to acquire the new updates in the box. The update command just downloads these updates locally.


Running the vagrant box update command will destroy your old vagrant box, and replace it with an updated one. This means that any data you have will be lost. If you want to keep your data, it’s better to create a new box for the update in a new directory.

You can find more help at the Box Versioning page.