Vagrant¶

Install Vagrant and VirtualBox¶

1. Install VirtualBox from https://www.virtualbox.org/ (or use your package manager). VirtualBox 5.1.18 or newer is required.
2. Install Vagrant from http://www.vagrantup.com/ (or use your package manager). Vagrant 1.9.3 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.

Open http://10.10.10.10.

The default login details are:

• Username: demo@example.com
• 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.

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:

//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 /home/user/Desktop/atom, feel free to modify this according to your environment.

Note that the directory where you have installed the vagrantfile on your host system (e.g. Desktop/atom-vagrant) will be accessible from inside the guest as /vagrant. So if you want to import a CSV called my-descriptions.csv from your host’s atom-vagrant directory, the command might look like:

php symfony csv:import /vagrant/my-descriptions.csv

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.

To pull in the latest code for your box, connect via SSH (see Connect to the terminal), navigate to the atom folder with cd atom, and run git pull --rebase. After pulling in new code, you will want to do the following:

• Clear cache: php symfony cc
• Restart services: sudo systemctl restart php7.4-fpm and sudo systemctl restart atom-worker

• Run the SQL upgrade task: php symfony tools:upgrade-sql
• Repopulate the search index: php symfony search:populate
• Compile stylesheets: make -C plugins/arDominionPlugin

If you are pulling in major changes to the AtoM codebase, we recommend purging the database back to the clean demo version (sudo php symfony tools:purge --demo) run the SQL upgrade task, and clear the cache and restart services. Then re-import some test data and repopulate the search index.

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.

You can find more help at the Box Versioning page.