Virtual appliance instructions

Main Page > Virtual appliance instructions

Distribution as a Virtual Appliance

Archivematica is distributed as a virtual appliance which integrates a number of software tools into one common virtual machine environment. A virtual appliance is one file containing a minimal operating system and server software. You can "play" this file with a free virtual machine player like VMware Player or Sun VirtualBox.

This allows Archivematica 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.

Minimum hardware requirements

• Processor: Intel core 2 or AMD Opteron
• Memory: 1 GB for the virtual appliance ('guest') operating system, i.e: if the 'host' operating system has 2 GB available, 1 GB needs to allocated to the 'guest'. Depending on the operating system, machines with less than 2 GB total memory will likely have trouble running Archivematica. Note that the default allocation setting in Archivematica is 512 MB; however, the more that is allocated the better the system will run. The setting can be changed once Archivematica is running.
• Hard Drive space: a minimum of 3 GB to test the system on a small scale (i.e. use the available test files or import a small set of test files); 12 GB or more for larger implementations

Instructions for using the VM image in VirtualBox

Install Oracle Virtual Box

• Archivematica uses the Open Virtualization Format and has been tested with the free and open-source Oracle Virtual Box virtualization platform.
• There are VirtualBox versions available for every major operating system.
  • Download and install Oracle VirtualBox: http://dlc.sun.com/virtualbox/vboxdownload.html. Note that if you are installing VirtualBox on Windows you will have to click through a number of warnings that you are attempting to install non-verified software.

Download Archivematica

• Download the latest version of the Archivematica appliance.
• Unzip the Archivematica file. This should result in the following file appearing in an Archivematica folder:
  • archivematica-0.9-beta.vmdk

Remember:
Be sure to take note of what location on your computer you choose to extract the file, so you can browse to it later when setting up the virtual appliance (instructions below).

Start Archivematica virtual appliance

1. Open the Oracle VirtualBox virtual machine.
2. Click New
3. Click Next

4. Set the name and type OS type (archivematica, linux-ubuntu)

5. Click Continue / Next
6. Set Memory to 1 GB (1024 MB) or higher

7. Click Continue
8. Select 'Use existing hard disk' and browse to and select archivematica-0.9-beta.vmdk

9. Click Continue. Review Summary and Click Create

10. The virtual box will open with Archivematica 0.9-beta listed on the left-hand side (in some cases "archivematica" will be listed on the left-hand side). Select Archivematica 0.9-beta and click Start (the green arrow in the menu).

USB Warning at Startup?





Depending on the setup and configuration of your computer peripherals, you may get this warning the first time you try to launch the Archivematica virtual appliance. Don't worry - it has nothing to do with the installation. We suggest simply checking "Don't show this message again," clicking OK, and proceeding. If you do want some guidance on troubleshooting USB detection in the Virtualbox, you can look at Oracle's troubleshooting instructions for USB detection in Linux here.




11. As the virtual appliance starts, you may have to select your machine from the list of available options. Hit return.
    
12. The image should launch, showing you a Linux Ubuntu desktop Login screen using the user name demo and the password demo. (on slower systems hitting return may cause the windows to reset, this is being addressed)

13. From here it is suggested that you use your external browser to access the archivematica dashboard (see Ubuntu login reset issue, below)
• Log into the Archivematica dashboard 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.
14. Congratulations, you have a running copy of Archivematica! See Documentation for instructions on how to use the software.

Important:
Archivematica may appear to crash when used as a virtual appliance. See Ubuntu login reset issue, below.

Ubuntu login reset issue

• Due to an issue with the Ubuntu 12.04.1 desktop, Archivematica may appear to crash when in use. The user will see a brief display of dingbat characters in the terminal, followed by a return to the Ubuntu login. Logging in will restore the dashboard and the user can continue processing. To avoid this issue, you can add settings to allow the Archivematica dashboard and ICA-AtoM to be accessed from your web browser, outside of the virtual machine. The steps are as follows:

1. Shut the virtual machine down if it is open.
2. In virtualbox select the archivematica virtual machine and click on Settings
3. Click the 'Network' tab
4. 'Adapter 1' should be set to NAT by default (this allows you to get to the internet); click on 'Adapter 2' tab
5. Click enable adapter and set attached to 'host only adapter'
   
   
6. Start the virtual machine
7. In your web browser, go to the url http://192.168.56.101/transfer/ (there is no need to login to the Archivematica virtual machine first). For ICA-AtoM, go to http://192.168.56.101/ica-atom/.
8. Congratulations! You can now use both Archivematica and ICA-AtoM via your web browser.

Import files into virtual appliance (optional)

If you want to use your own files in addition to the sample data provided, proceed with the following directions:

Using SFTP

It's possible to use SSH File Transfer Protocol (SFTP), through an FTP client to upload your own content from your computer to the virtual desktop where Archivematica is running:

1. While in virtualbox right click the archivematica virtualmachine and click settings
2. Click the 'Network' tab
3. 'Adapter 1' should be set to NAT by default(this allows you to get to the internet), click on 'Adapter 2' tab
4. Click enable adapter and set attached to 'host only adapter'
   
   
5. Power up the archivematica virtualmachine
6. Once in the xubuntu interface goto Applications > Accessories > Terminal

   Having trouble locating the Applications menu?
   You can find applications by clicking on the little blue logo in the top left-hand corner of the virtual desktop: . Alternately, you can access the terminal by simply right-clicking anywhere in the virtual desktop, and selecting "Open terminal here."

   
   

7. Type the following in terminal (the password is demo) - this will take a minute and requires internet

   sudo aptitude install ssh 

   Update packages?
   

   If the terminal asks you to update and/or install new packages, do so. Hit "y" and return.
   
   

   
   

8. type "ifconfig" in the terminal. You should see an IP address like '192.168.56.101' (likely eth1 interface)

   $ ifconfig
   eth1      Link encap:Ethernet  HWaddr fe:54:00:9d:92:64  
             inet addr:192.168.56.101  Bcast:192.168.56.255  Mask:255.255.255.0
             inet6 addr: fe80::1c6b:7bff:fe07:ddb6/64 Scope:Link
             UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
             RX packets:24 errors:0 dropped:0 overruns:0 frame:0
             TX packets:45 errors:0 dropped:0 overruns:0 carrier:0
             collisions:0 txqueuelen:0 
             RX bytes:1400 (1.4 KB)  TX bytes:5815 (5.8 KB)
   

   
   

9. From here, your machine should be connectable via SFTP. Download an SFTP client; a popular open-source option is FileZilla, which works on Linux and Windows. If you are using Apple's OSX or higher, Cyberduck is reported to be a decent open-source SFTP client.
   
   SFTP 101: Whats am I setting up here?
   

   File Transfer Protocol (FTP) "is a standard network protocol used to transfer files from one host or to another host over a TCP-based network, such as the Internet" (Wikipedia). In this case, you will be using SFTP to transfer your files, which is an FTP protocol that uses a Secure Shell (SSH) extension for more secure data transmission. When you use FizeZilla or Cyberduck, you are using an FTP clientthat provides a graphical user interface (GUI) to allow you to move files easily from one host (in this case, your computer) to another (the virtual desktop).

   
   

10. The connection information should be as follows

    username: demo
    password: demo
    IP/Hostname: 192.168.56.101 < results of ifconfig likely '192.168.56.*'
    port: 22
    destination folder:   /home/demo/ < if this is not set you will have to navigate to /home/demo directory 
    

    
    

    • Here is an example of setting up the connection information in FileZilla.

    
    
    

    • Note that the username, password, and host are all input into the top of the FileZilla browser.
    • In FileZilla, your home computer's directory is displayed on the left hand side, while Archivematica's virtual appliance directory is on the right hand side. Once the connection is established, you can drag and drop content from one side to the other to upload content.
    • If you require more support using FileZilla, please visit their documentation wiki here.
    • If you have dragged your content to the /home/demo folder, you can find your content in the Archivematica virtual appliance window by clicking on the "Home" icon on the desktop:

    
    
    
    

    • Here is an example of setting up the connection information in Cyberduck:

    

    • Cyberduck will only show one directory, so you may have to click on the Action button and select "Upload" to change the display and reveal Archivematica's directory.

    

    • You will need to create a new folder inside an existing Media folder to upload your media files into. For example, double click on the arrow to open the "Pictures" folder and then create new folder in it and upload your digital images.

    

    • All further actions will occur in the Archivematica dashboard and instructions can be found in the User Manual under Transfer.

    
    

    Using Virtual Box Guest Additions

    Another way of adding content to Archivematica is through the use of shared folders via Guest Additions in your Virtualbox. Here is a description of the process from the Virtualbox documentation:

    With the "shared folders" feature of VirtualBox, you can access files of your host system from within the guest system. This is similar how you would use network shares in Windows networks -- except that shared folders do not need require networking, only the Guest Additions. Shared Folders are supported with Windows (2000 or newer), Linux and Solaris guests.

    Shared folders must physically reside on the host and are then shared with the guest, which uses a special file system driver in the Guest Addition to talk to the host. For Windows guests, shared folders are implemented as a pseudo-network redirector; for Linux and Solaris guests, the Guest Additions provide a virtual file system.

    To share a host folder with a virtual machine in VirtualBox, you must specify the path of that folder and choose for it a "share name" that the guest can use to access it. Hence, first create the shared folder on the host; then, within the guest, connect to it.

    
    Here's how to set it up:

    1. In the terminal, run Jockey

       sudo jockey-gtk

    2. Select Guest Additions from available drivers
    3. Restart

    References https://help.ubuntu.com/community/VirtualBox/SharedFolders http://www.virtualbox.org/manual/ch04.html#sharedfolders

    Turn off virtual machine

    • At the end of your session, turn off the VirtualBox 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.