Virtual appliance instructions

Main Page > Virtual appliance instructions

Archivematica is distributed as a virtual appliance which integrates a number of software tools into one common virtual machine environment.

This allows it to be run on almost any workstation or server hardware without compromising the host machine's operating system or application software. At the same time, the virtual appliance is able to interact with any number of networked and/or external storage devices to allow for the flexible implementation of an archival storage and backup strategy.

• See the software page for a full list of the tools used in each system release.
• See the documentation page for instructions on how to use the virtual appliance to accomplish the system requirements

Instructions for using the VM image

Download virtual box

• Download Sun VirtualBox (see http://www.sun.com/software/products/virtualbox/index.jsp).

Unzip Archivematica image

• Extract Archivematica-0.3.2.tar.gz by right-clicking the tar.gz file and choosing "extract here". This should result the following being created within an archivematica folder:
  • Archivematica-0.3.2.ovf
  • disk0.vmdk

Create Archivematica virtual machine

• Open the virtual box.
• Click File > Import Appliance
• Click Choose
• Select Archivematica-0.3.2.ovf
• Click Open
• Click Next
• Click Import
• Read and agree to the Software License Agreement
• The virtual box will open with Archivematica 0.3.2 listed on the left-hand side. Select Archivematica 0.3.2 and click Start (the green arrow in the menu)
• The image should launch, showing you a Linux Ubuntu desktop and the digital preservation applications which are currently part of Archivematica 0.3.2.
  • You may have to login using the user name demo and the password demo.
  • If your mouse pointer does not appear to be working in the virtual machine, click the letter f while holding down the right-hand control button. Do the same thing to switch back to using your mouse pointer outside the virtual box.

Import files into virtual machine (optional)

Creating a shared folder allows you to add files to a folder on the host machine and have them appear in a folder in the virtual machine (VM). If choose not to implement this option, you can use test files located in home/demo/ingest/ to test Archivematica's functionality.

1. Create a folder on the host machine.

2. Set up the shared folder in VirtualBox

• From within the Sun VirtualBox application, select the current version of the Archivimatica appliance and click on the "Settings" button below the main menu bar. Note that the application must not be running in order to be able to slect the settings.
• In the Settings dialogue, select "Shared Folders" (under "Details" tab).
• Click on the "Add Share" icon on the right side of the window (the folder with the plus sign) and navigate to the folder you created in step 1. Give the shared folder a name that VirtualBox can use to identify it. The default is the name the folder already has in the host system; note that due to Linux limitations you should create a folder name that has no capital letters or special characters (such as underscores).
• Click OK.

3. Mount the shared folder in the VM

• Launch the Archivimatica appliance in VirtualBox.
• Open a command line interface in Ubuntu: <ctrl><alt><F1>
• Login as demo and use the password demo
• Grant the demo account /root privileges by typing "sudo -s", and give the demo account password when prompted
• Mount the shared folder by using the following command:

  mount -t vboxsf <folder name (the name you gave the folder in the Virtual Box Settings menu)> <filepath in Linux>. Example: mount -t vboxsf sharedfolder /home/demo/Documents

• type "exit" to exit from your root login
• type "exit" to exit from your demo login
• Return to the Gnome GUI <ctrl><alt><F7>

You should now be able to see and manipulate the contents of both folders from within both the host environment and the guest Ubuntu environment.

Note that if you close Archivematica by sending the shutdown signal or powering off (as opposed to saving the machine state) you will need to re-mount the shared folder(s) when Ubuntu starts again. See "Turn off virtual machine", below.

Turn off virtual machine

• At the end of your session, turn off the virtual machine by going to Machine > Close > and selecting one of the three shutdown options. It is best to choose either "Save the machine state" or "Send the shutdown signal". This is from the VirtualBox help manual:

3.4.3. Saving the state of the machine

When you click on the "Close" button of your virtual machine window (at the top right of the window, just like you would close any other window on your system) (or press the Host key together with "Q"), VirtualBox asks you whether you want to "save" or "power off" the VM.

The difference between these three options is crucial. They mean:

Save the machine state: With this option, VirtualBox "freezes" the virtual machine by completely saving its state to your local disk. When you later resume the VM (by again clicking the "Start" button in the VirtualBox main window), you will find that the VM continues exactly where it was left off. All your programs will still be open, and your computer resumes operation.

Saving the state of a virtual machine is thus in some ways similar to suspending a laptop computer (e.g. by closing its lid).

Send the shutdown signal. This will send an ACPI shutdown signal to the virtual machine, which has the same effect as if you had pressed the power button on a real computer. So long as a fairly modern operating system is installed and running in the VM, this should trigger a proper shutdown mechanism in the VM.

Power off the machine: With this option, VirtualBox also stops running the virtual machine, but without saving its state.

This is equivalent to pulling the power plug on a real computer without shutting it down properly. If you start the machine again after powering it off, your operating system will have to reboot completely and may begin a lengthy check of its (virtual) system disks.

As a result, this should not normally be done, since it can potentially cause data loss or an inconsistent state of the guest system on disk.

The "Discard" button in the main VirtualBox window discards a virtual machine's saved state. This has the same effect as powering it off, and the same warnings apply.

Instructions for using Archivematica

Location of test files

• Test files are located in home/demo/ingest/.

Generating checksums

• Select the files for which you would like to generate the checksums. Please note that as of the current version of Archivematica you cannot select folders, only files.
• Right click, then select Scripts > makeMD5.
• Save the report in the same folder.
• Copy all the files, including the MD5 report, to another folder (eg. archivalstorage)
• Right-click the report, then select Scripts > checkMD5
• The report should tell you that all files are OK. If you didn't move over all the files or if there was a problem which changed one or more of the files, the report will tell you that the checksum for those files failed.

Using DROID

• DROID provides a gui interface for selecting objects for processing. Navigate to home/demo/ingest/ and select the entire folder, or open the folder to select individual files.
• DROID allows you to select an "include subfolders" option.
• When the files are processed, go to File > Save List to save an xml report of the results.

Using NLNZ Metadata Extraction Tool

• Creating a simple object will result in one xml report for each object; creating a complex object will create a single report for all objects.
• When you create a new object in NLNZ, you will be asked to select the directory: enter /home/demo/ingest/.
• The xml reports are set to output to usr/local/OAIS/metadata-extractor/harvested/nlnz_dd/.

Using JHOVE

• To include calculation of checksums in the validation process, go to Edit > Preferences and click Calculate checksums.
• To process a directory of records, click File > Open URL and enter the directory: /home/demo/ingest/.
• To save an xml report, in the RepInfo window click on File > Save as; under Choose output handler select xml; then create a file name with the .xml extension added (otherwise JHOVE will save the report as plain text).

Using Qubit

• Qubit is an open-source software toolkit that allows institutions such as archives, libraries, museums, and art galleries to manage and host web-based collections of information resources.
  • It is currently being implemented in the archival community as ICA-AtoM (International Council on Archives Access to Memory).
    • Please refer to the ICA-AtoM user manual for instructions on how to use a typical Qubit application.
• Qubit is being evaluated for use in the archivematica Data Management and Access components.
• Please note that the VM version of Qubit is a development version, not a stable release.
• Log in to Qubit using the user name demo@example.com and the password demo.

Using Xena

• Click Add Directory to normalize a body of records.
• Select home/demo/ingest. Note that Xena will normalize the contents of the folder and any subfolders.
• The default directory for Xena output is home/demo/xena-output/.
• The Xena log will save automatically as home/demo/xena-output/xena-log.
• To view a normalized file, double-click on a file in the normalization results screen. For office documents, you will then need to select the option to view in OpenOffice.org.
  • If OpenOffice.org appears not to be working or takes a long time to open, go to Tools > Plugin Preferences >, and for "Sleep time allowed for OpenOffice to start (seconds)" select 3.

Using Bagit

• Select a group of files or a folder.
• Right-click, then select Scripts > Bagit.
• Edit the name of the bag if desired.
• The bag will automatically be saved to home/demo/mybags/.