Difference between revisions of "Virtual appliance instructions"

From Archivematica
Jump to navigation Jump to search
(Make deprecation warning more visible.)
 
(116 intermediate revisions by 11 users not shown)
Line 1: Line 1:
 
[[Main Page]] > Virtual appliance instructions
 
[[Main Page]] > Virtual appliance instructions
  
 +
{| class="wikitable" style="background-color:#ffcccc; font-size: 120%; font-weight: bold; " cellpadding="10"
 +
| Please note: Virtual appliance instructions were for last beta release: 0.10 - these notes are no longer supported. Instead please see: [[Getting started]]
 +
|}
  
 +
= Distribution as a Virtual Appliance =
  
−
Archivematica is distributed as a [http://en.wikipedia.org/wiki/Virtual_appliance virtual appliance] which integrates a number of software tools into one common virtual machine environment.  
+
Archivematica is distributed as a [http://en.wikipedia.org/wiki/Virtual_appliance 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 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.
+
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 [[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]].
 
*See the [[documentation]] page for instructions on how to use the virtual appliance to accomplish the system [[requirements]].
−
 
+
</br>
  
 
=Minimum hardware requirements=
 
=Minimum hardware requirements=
  
 
*Processor: Intel core 2 or AMD Opteron
 
*Processor: Intel core 2 or AMD Opteron
−
*Memory: 512MB for the virtual appliance ('guest') operating system, i.e: if the 'host' operating system has 2GB available, 512MB needs to allocated to the 'guest'. Depending on the operating system, machines with less than 1.5GB total memory will likely have trouble running Archivematica. Note that the default allocation setting in Archivematica is 512MB; however, the more that is allocated the better the system will run. The setting can be changed once Archivematica is running.
+
*Memory: 2 GB for the virtual appliance ('guest') operating system, i.e: if the 'host' operating system has 4 GB available, 2 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 3GB to test the system on a small scale (i.e. use the available test files or import a small set of test files); 12GB or more for larger implementations
+
*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=
+
</br>
  
−
==Install Sun Virtual Box==
+
=Instructions for using the VM image in VirtualBox=
  
−
*Archivematica uses the [http://en.wikipedia.org/wiki/Open_Virtualization_Format Open Virtualization Format] and has been tested with the free and open-source [http://www.sun.com/software/products/virtualbox/index.jsp Sun Virtual Box ] virtualization platform.  
+
==Install Oracle Virtual Box==
 +
 
 +
*Archivematica uses the [http://en.wikipedia.org/wiki/Open_Virtualization_Format Open Virtualization Format] and has been tested with the free and open-source [http://www.sun.com/software/products/virtualbox/index.jsp Oracle Virtual Box ] virtualization platform.  
 
*There are VirtualBox versions available for every major operating system.
 
*There are VirtualBox versions available for every major operating system.
−
**Download and install Sun VirtualBox: [http://dlc.sun.com/virtualbox/vboxdownload.html http://dlc.sun.com/virtualbox/vboxdownload.html].
+
**Download and install Oracle VirtualBox: [http://dlc.sun.com/virtualbox/vboxdownload.html 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 Archivematica ==
  
−
*[[Download]] the latest version of the Archivematica appliance.
+
*[http://archivematica.org/download Download] the latest version of the Archivematica appliance.
−
*Unzip the Archivematica file. This should result in the following two files appearing in an Archivematica folder:
+
*Unzip the Archivematica file. This should result in the following file appearing in an Archivematica folder:
−
**Archivematica-0.x.ovf
+
**archivematica-0.10-beta.vmdk
−
**disk0.vmdk
+
 
 +
</br>
 +
<div class="note">
 +
<strong>Remember:</strong>
 +
</br>
 +
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).
 +
</div>
 +
</br>
 +
 
 +
== Start Archivematica virtual appliance ==
  
−
==Start Archivematica virtual appliance==
 
  
−
*Open the Sun VirtualBox virtual machine.
+
<ol>
−
*Click File > Import Appliance
+
<li>Open the Oracle VirtualBox virtual machine.</li>
−
*Click Choose
+
<li>Click New</li>
−
*Select ''Archivematica-0.5.ovf''
+
<li>Click Next</li>
−
*Click Open
+
[[File:new_next_VMWizard.png]]
−
*Click Next
+
<li>Set the name and type OS type (archivematica, linux-ubuntu)</li>
−
*Click Import
+
[[File:2_VM_Name_OS_type.png]]
−
*Read and agree to the Software License Agreement (GPL2)
+
<li>Click Continue / Next</li>
−
*The virtual box will open with Archivematica 0.5 listed on the left-hand side. Select Archivematica 0.5 and click Start (the green arrow in the menu).
+
<li>Set Memory to 2 GB (2048 MB) or higher</li>
−
*The image should launch, showing you a Linux Ubuntu desktop and some of the digital preservation applications which are included in Archivematica 0.5
 
−
**You may have to log in 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.
 
−
*Congratulations, you have a running copy of Archivematica! See [[Documentation]] for instructions on how to use the software.
 
  
−
==Import files into virtual appliance (optional)==
+
<li>Click Continue</li>
−
Creating shared folders allows you to add files to folders on the host machine and have them appear in folders in the virtual appliance. and vice versa. If you choose not to implement this option, you can use test files located in home/demo/testFiles to test Archivematica's functionality.
+
<li>Select 'Use existing hard disk' and browse to and select archivematica-0.10-beta.vmdk</li>
 +
<li>Click Continue. Review Summary and Click Create</li>
 +
<li>The virtual box will open with Archivematica 0.10-beta listed on the left-hand side (in some cases "archivematica" will be listed on the left-hand side). Select Archivematica 0.10-beta and click Start (the green arrow in the menu).</li>
 +
[[File:6_start_archivematica_VM.png]]
  
 +
<div class="note"><strong>USB Warning at Startup?</strong>
 +
</br>
 +
[[File:error_USB_setup.png]]
 +
</br>
  
−
In this example, we create a folder called sendSIP on the host machine and link it to a folder called ingestSIP in Archivematica.
+
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 [http://www.virtualbox.org/manual/ch12.html#ts_usb-linux here].
 +
</div>
 +
</br>
 +
<li>As the virtual appliance starts, you may have to select your machine from the list of available options. Hit return.
 +
</br>
 +
[[File:inside_the_VM.png]]
 +
<li>From here it is suggested that you use your external browser to access the archivematica dashboard. Due to an issue with the Ubuntu 12.04.1 desktop, we suggest you 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 [Please note, you may need to adjust your virtualbox preferences prior to taking this step. To do so, simply go to the network section of virtualbox preferences and click the "add" button, then save your change):
  
 +
<ol>
 +
<li> Shut the virtual machine down if it is open.
 +
<li> In virtualbox select the archivematica virtual machine and click on Settings
 +
<li> Click the 'Network' tab
 +
<li> 'Adapter 1' should be set to NAT by default (this allows you to get to the internet); click on 'Adapter 2' tab
 +
<li> Click enable adapter and set attached to 'host only adapter'
 +
</br>
 +
[[File:selecting_host_only_adapter.png]]
 +
</br>
 +
<li> Start the virtual machine
 +
<li> 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/.
 +
<li>Congratulations! You can now use both Archivematica and ICA-AtoM via your web browser.
 +
</ol></li>
  
−
1. Create a folder on the host machine and give it the name sendSIP.
+
* Log into the Archivematica dashboard using the user name ''demo'' and the password ''demo''.  
−
*Note the following naming constraints when setting up shared folders:
+
* 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.
−
**Do not use special characters or spaces in the folder name, since these will not be recognized by Linux;
 
−
**Do not give the folder on the host machine the same name as the shared folder in Archivematica. This will cause the attempt to mount the shared folder (Step 3, below) to fail.
 
  
 +
<li>Congratulations, you have a running copy of Archivematica! See [[Documentation]] for instructions on how to use the software.</li>
 +
</ol>
 +
</br>
 +
<div class="note">
 +
'''Important:'''</br> Archivematica may appear to crash when used as a virtual appliance. See Ubuntu login reset issue, below.
 +
</div>
  
−
2. Set up the shared folder in VirtualBox
+
=== Permissions ===
−
*While Archivematica is open, go to Devices > Shared Folders in the VirtualBox menu (top-left corner of your screen)
 
−
*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.
 
−
*Click OK to select the folder, then OK again to exit the Shared Folders window.
 
  
 +
Users that are depositing files via ssh should be added to the archivematica group. 
  
−
3. Mount the shared folder in the VM
+
This can be done with:  
−
*Open a command line interface in Ubuntu by selecting Applications > Accessories > Terminal.
+
$ sudo useradd -G archivematica Username
−
*Grant the demo account root privileges by typing "sudo -s", and give the demo account password when prompted (pressing ''Enter'' on your keyboard after each command):
 
−
  demo@ubuntu:~$ sudo -s
 
−
  [sudo] password for demo: demo
 
−
*Mount the shared folder by using the following command:
 
−
  root@ubuntu:~# mount -t vboxsf -o rw,exec,uid=1000,gid=1000 sendSIP /home/demo/ingestSIP
 
−
*This connects the sendSIP folder on your host machine to the folder ingestSIP in Archivematica and sets the permissions to add, modify and delete folders and files within receiveSIP.
 
−
*type "exit" to exit from your root login.
 
−
*type "exit" to exit from your demo login and the command line interface.
 
  
 +
In the Virtual Machine, the demo user is already apart of this group.
  
−
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.
+
At a minimum, your deposited files should have the following permissions in order to upload them to the dashboard through source directories in the administration tab: rw-rw----  or rwxrwx---
  
−
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==
 
==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:
+
*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".  
 +
#:
 +
[[file:archivematica_shutdown.png]]
 +
#:
 +
[[file:archivematica_shutdown2.png]]
 +
#:
 +
 
 +
 
 +
This is from the VirtualBox help manual:
  
 
<blockquote>3.4.3. Saving the state of the machine</blockquote>
 
<blockquote>3.4.3. Saving the state of the machine</blockquote>

Latest revision as of 13:57, 20 June 2016

Main Page > Virtual appliance instructions

Please note: Virtual appliance instructions were for last beta release: 0.10 - these notes are no longer supported. Instead please see: Getting started

Distribution as a Virtual Appliance[edit]

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[edit]

  • Processor: Intel core 2 or AMD Opteron
  • Memory: 2 GB for the virtual appliance ('guest') operating system, i.e: if the 'host' operating system has 4 GB available, 2 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[edit]

Install Oracle Virtual Box[edit]

  • 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[edit]

  • 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.10-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[edit]

  1. Open the Oracle VirtualBox virtual machine.
  2. Click New
  3. Click Next
    4. New next VMWizard.png
  4. Set the name and type OS type (archivematica, linux-ubuntu)
    5. 2 VM Name OS type.png
  5. Click Continue / Next
  6. Set Memory to 2 GB (2048 MB) or higher
  7. Click Continue
  8. Select 'Use existing hard disk' and browse to and select archivematica-0.10-beta.vmdk
  9. Click Continue. Review Summary and Click Create
  10. The virtual box will open with Archivematica 0.10-beta listed on the left-hand side (in some cases "archivematica" will be listed on the left-hand side). Select Archivematica 0.10-beta and click Start (the green arrow in the menu).
    11. 6 start archivematica VM.png
    USB Warning at Startup?


    Error USB setup.png

    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.
    Inside the VM.png
  12. From here it is suggested that you use your external browser to access the archivematica dashboard. Due to an issue with the Ubuntu 12.04.1 desktop, we suggest you 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 [Please note, you may need to adjust your virtualbox preferences prior to taking this step. To do so, simply go to the network section of virtualbox preferences and click the "add" button, then save your change):
    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'
      Selecting host only adapter.png
    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.
    • 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.
  13. 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.

Permissions[edit]

Users that are depositing files via ssh should be added to the archivematica group.

This can be done with: 

$ sudo useradd -G archivematica Username

In the Virtual Machine, the demo user is already apart of this group.

At a minimum, your deposited files should have the following permissions in order to upload them to the dashboard through source directories in the administration tab: rw-rw---- or rwxrwx---


Turn off virtual machine[edit]

  • 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".

Archivematica shutdown.png

Archivematica shutdown2.png


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.

Retrieved from "https://wiki.archivematica.org/index.php?title=Virtual_appliance_instructions&oldid=11135"