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¶
Spin it up¶
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
Initialize the current directory to be a Vagrant environment.
vagrant init artefactual/atom
Run Vagrant (again, from the same directory where you saved the Vagrantfile).
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:
Connect to the terminal¶
vagrant ssh from the same directory as where you ran
Vagrant will connect you to the correct virtual machine.
The login details are:
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:
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.
- 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.
- Ideally, you will also update the system to use your current timezone. See how to change the timezone from the command line in Ubuntu.
- Set up your username and email in Git.
- 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.
vagrant ssh -- -Aor
vagrant ssh -- -o ForwardAgent=yesinstead of just
vagrant ssh. Alternatively, you can set
truein the local Vagrantfile or the global
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
//10.10.10.10/vagrant /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
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.
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.