Access to Memory (AtoM) is an open source web application for standards-based archival description and access - learn more at: https://www.accesstomemory.org To provide users with an easy to install local environment for testing and development, Artefactual maintains a version of AtoM that can be installed on a laptop or home computer, regardless of operating system. We have slides that will explain what Vagrant is and how to install the AtoM Vagrant box here: http://bit.ly/AtoM-Vagrant These slides will help users create a re-usable set of data for use in a local AtoM Vagrant environment. Having a set of data that can easily be reloaded will make the AtoM Vagrant box more useful to local testers and developers. The slides were originally created by Dan Gillean, AtoM Program Manager, for use in a series of training workshops delivered July 9-13, 2018 at the University of the Witswatersrand in Johannesburg, South Africa. The slides are based on current functionality in AtoM release 2.4 - they have been tested in the AtoM 2.4.0.2 and 2.5.0.0 Vagrant boxes.

1. CREATING YOUR OWN ATOM DEMO DATA SET
for re-use with Vagrant

2. What is Vagrant?
Vagrant is a tool for building complete
development environments. With an
easy-to-use workflow and focus on
automation, Vagrant lowers development
environment setup time, increases
development / production parity, and
makes the "works on my machine" excuse
a relic of the past.
Vagrant was started in January 2010 by
Mitchell Hashimoto.
https://www.vagrantup.com/about.html
Vagrant remains and always will be a liberally licensed open
source project. Each release of Vagrant is the work of hundreds
of individuals' contributions to the open source project.

3. What is VirtualBox?
VirtualBox is an open source, cross-platform
virtualization application.
When we describe VirtualBox as a "virtualization" product, we
refer to "full virtualization", that is, the particular kind of
virtualization that allows an unmodified operating system with
all of its installed software to run in a special environment, on
top of your existing operating system. This environment, called
a "virtual machine", is created by the virtualization software by
intercepting access to certain hardware components and
certain features. The physical computer is then usually called
the "host", while the virtual machine is often called a "guest".
Most of the guest code runs unmodified, directly on the host
computer, and the guest operating system "thinks" it's running
on a real machine.
https://www.virtualbox.org/wiki/Virtualization

4. The AtoM Vagrant Box
AtoM and all of its
dependencies….
Are packaged as a
Vagrant box…
Which is run by VirtualBox
as a virtual machine…
And accessed via SSH
and/or a web browser.

5. The AtoM Vagrant Box
The AtoM Vagrant box is an easy way to install
a test instance of AtoM on a local laptop or
personal computer, for testing, development,
and training.
Because the installation environment is
virtualized, you can install and run the AtoM
Vagrant box on almost any local operating
system (e.g. Windows, Mac, Linux, etc).
WARNING: The AtoM Vagrant box is NOT
intended to be used as a production
environment!

6. AtoM Vagrant Box Installation
Documentation
http://bit.ly/AtoM-Vagrant-docs
Slides
http://bit.ly/AtoM-Vagrant

7. BUT WE NEED SOME REUSABLE
FOR OUR TEST ENVIRONMENT!
https://pxhere.com/en/photo/1172040

8. Option 1: Create your own
AtoM Documentation
https://www.accesstomemory.org/docs/latest/
Use the documentation to guide
you as you create new records via
the user interface.

9. Option 2: Visit some public AtoM sites
AtoM Users
https://wiki.accesstomemory.org/Community/Users
Use the Clipboard and the various
export options to gather some
publicly accessible samples. Check
the AtoM documentation for
export and import instructions.
NOTE: If you intend to use or share this
data publicly, you should contact the site
admins for permission.

10. AtoM Vagrant database credentials
> nano config/config.php
Use CTRL+X to exit
Default credentials:
• Database name: atom
• Username: atom-user
• Password: ATOMPASSWORD
If you have changed these
defaults or simply want to
check the current credentials,
you will find them listed in
the config/config.php
configuration file.

11. Back up your database
> mysqldump -u atom-user -pATOMPASSWORD atom > /vagrant/atom2_demo.sql
This will copy the contents of your AtoM MySQL database to a
new database dump, called atom2_demo.sql. The file will be
located in the Vagrant installation directory on your host computer
– that is, the directory where you first ran the vagrant init
command when setting up the AtoM Vagrant box on your local
computer.

12. Back up your uploads directory
> cp -r /home/vagrant/atom/uploads/ /vagrant/
This will copy the contents of your AtoM uploads directory (digital
object uploads, repository logos and banners) to a new directory
called uploads in the Vagrant installation directory on your local
computer

13. Deleting your current data
> rm –rf /home/vagrant/atom/uploads
This will purge ALL data in the database, and create a new default
Admin user (username: demo, email: demo@example.com,
password: demo).
> php symfony tools:purge --demo
This will delete everything inside the current uploads directory.

14. Manually reloading your data
> rsync –av /vagrant/uploads/r /home/vagrant/atom/uploads
This will load the atom2_demo.sql database dump back into
your current AtoM database.
> mysql -u atom-user -pATOMPASSWORD atom < /vagrant/atom2_demo.sql
This will copy the contents of your local uploads directory into
the uploads directory in the AtoM Vagrant box.

15. Runing maintenance tasks
This will load the atom2_demo.sql database dump back into
your current AtoM database.
> php symfony digitalobject:regen-derivatives
> php symfony search:populate
> sudo systemctl restart php7.0-fpm
> sudo systemctl restart memcached
> sudo systemctl reload nginx
> sudo systemctl restart atom-worker
> php symfony cc
These commands will regenerate the digital object derivatives, re-
populate the search index, restart all services, and clear the
application cache.

16. https://i.ytimg.com/vi/qJehYddjLJ4/maxresdefault.jpg

17. Bash scripting to the rescue!
$_
http://onemillionskates.com/inside-edge/a-true-hero-dad-this-ones-for-you
Bash is a Unix shell and command
language written by Brian Fox for
the GNU Project as a free software
replacement for an older
command-line interface called the
Bourne shell. First released in 1989,
it has been distributed widely as
the default login shell for most
Linux distributions and Apple's
macOS (formerly OS X).

18. Bash scripting to the rescue!
Artefactual has prepared a simple bash script that will purge your current
environment, reload your data, and run the maintenance commands. Get
the script here: http://bit.ly/AtoM-bash

19. DANGER!!!
This script is provided AS
IS. Artefactual bears no
responsibility for any errors
or unexpected outcomes
caused by this script.
PROCEED AT YOUR OWN RISK
https://steemit.com/health/@kyusho/danger-will-robinson

20. Setting up the bash script
../atom-vagrant/ ← Wherever you’ve installed Vagrant
├── .vagrant ← The vagrant directory, created during set up
├── atom2_demo.sql ← The AtoM demo data database dump
├── uploads ← The AtoM demo data uploads directory
│ └── r ← Inside the uploads dir, the r dir
├── load-demo.sh ← The bash script
├── Vagrantfile ← The vagrantfile created when you set up Vagrant
Download and unzip the bash script, and place it
in your Vagrant installation directory – AKA
wherever you first ran the vagrant init
command on your local computer. It should be the
same place you now have your database dump
and uploads directory.

21. Make the script executable
> chmod +x /vagrant/load-demo.sh
This will make the script executable.
chmod is a Unix command used to manage filesystem permissions
– it’s short for “change mode.” The +x tells the filesystem to make
this file executable by all users.

22. Running the script
> /vagrant/load-demo.sh
Once you execute the script, remember:
• all your previous data will be purged and overwritten!
The script will spit out a bunch of lines as it runs through all of the
commands. Length of time will depend on how much data you have – as an
example, the AtoM public demo data takes about 5 minutes to fully refresh.
That’s it!

23. What does the script actually do?
php symfony tools:purge --demo
Run the tools:purge command with the demo option. Purge all current data, and create a
new demo user (demo@example.com, p: demo).
rm -rf /home/vagrant/atom/uploads
Recursively delete the current contents of the uploads directory in the AtoM vagrant box.
rsync -av /vagrant/uploads/r /home/vagrant/atom/uploads
Copy the contents of our fresh uploads directory into the AtoM Vagrant box using rsync.
mysql -u atom-user -pATOMPASSWORD -e 'drop database atom; create
database atom character set utf8 collate utf8_unicode_ci;'
Drop and recreate the AtoM database.

24. What does the script actually do?
mysql -u atom-user -pATOMPASSWORD atom < /vagrant/atom2_demo.sql
Load the AtoM demo database dump into the new AtoM database in Vagrant.
php symfony tools:upgrade-sql -B
Run the sql-upgrade task to make sure that the database schema is up to date.
php symfony digitalobject:regen-derivatives
Regenerate the digital object derivatives from the fresh master digital objects we have loaded.
php symfony search:populate
Repopulate the search index.

25. What does the script actually do?
sudo systemctl restart php7.0-fpm
Restart PHP-FPM.
sudo systemctl restart memcached
Restart memcached.
sudo systemctl reload nginx
Restart Nginx.
sudo systemctl restart atom-worker
Restart the atom-worker, used by the job scheduler for asynchronous tasks.
php symfony cc
Clear the application cache.

26. Troubleshooting the script
set -o errexit
set -o nounset
set -o pipefail
# set -o xtrace --> FOR DEBUGGING!
The # pound symbol comments out a line
in bash, so it is not executed.
If you uncomment the last line (and make
sure you remove the --> FOR
DEBUGGING! part too!), you can see how
the script runs step by step, which can be
useful for figuring out where something is
going wrong.
Note that in the script on line 6, there is a debug line, currently commented out:

27. QUESTIONS?
info@artefactual.com