|Table of Contents|
First, register an account on HTRC portal on the production stack, from where you will access the HTRC Data Capsule.
Install a VNC Client on your computer to enable the communication between your computer and the capsule, which is a virtual machine, to be created. You can choose any VNC client you prefer.
We use VNC View for Google Chrome in this tutorial so also recommend people install the same. Install and launch the app.
Getting Familiar with the Data CapsuleLog in to the HTRC portal where you just created an account and sign in. Create a capsule by clicking on the "HTRC Data Capsule" and then "Create Virtual Machine" on the top of the page
Once you have your capsule running, you may find it useful to open this guide in an internet browser in your capsule so you can copy and paste commands. The short link for this page is: https://wiki.htrc.illinois.edu/x/TQFRAQ.
From the Analytics homepage, create a capsule by clicking on Capsule on the top menu. You will be asked to provide information about the capsule you would like to create.Start the
This step also explains how to create or convert an existing Capsule to one with access to the full HathiTrust corpus, for HathiTrust members only.
Start the capsule youwere assigned Please refer to the Data Capsule FAQ Frequently Asked Questions (FAQ)
created by clicking the Start Capsule button on the"Start VM" button on the Virtual Machines list page (make sure you have logged in the portal in order to see the page).
After starting the capsule, you can connect to and operate on the capsule via the VNC Client you just installed. Use the "Host Name" and "VNC port" fields of the capsule as input to the VNC Client: put them the "Address" field of the VNC Viewer, separated by a semicolon.
Each capsule is designed to have 2 modes: maintenance node and secure modes. Under the "Virtual Machines" page, click on "Switch to Secure Mode" or "Switch to Maintenance Mode" buttons to switch between modes.
Under maintenance mode, user is allowed to access network freely except for HTRC corpus repository and install whatever software she wants. In secure mode, network access is restricted. User is only allowed to access a few network addresses e.g., HTRC corpus repository and search service.
Run text analysis experiments in the capsule. Details of conducting experiments are demonstrated in the 4 use cases below. If users want to export results out of the capsule, they can release the result in the capsule's secure mode.
Interact with the capsule either via Remote Desktop viewer or Terminal viewer.
Alternatively, you can SSH into your capsule when it is in maintenance mode only.
First, you will need a public key. Click "Advanced Features" in the blue box to establish your public key at the bottom of your Capsules page.
You will be prompted for a key. If you do not yet have a public key set up, then entering one will establish your key. If you already have a key, resubmitting a response in this box with change your key.
You'll find the command to SSH into your capsule in the blue "Advanced Features" box on each capsule's status page.
Switch between maintenance and secure mode.
Share your Research Data Capsule with up to 5 other researchers.
From your capsule listing page, click on the Data Capsule ID for the capsule you would like to share.
Then, click the button that says Manage Collaborators.
You will be taken to a new page, where you can input the email address for the user you would like to add.
The email address must be the one associated with their HTRC Analytics account or you will get an error.
When you successfully add a collaborator, that user's information will appear in the table of collaborators. By default, they will have the role of Contributor. Contributors can access the capsule and interact with it in its current state. You will have the role of Owner-Controller.
Once complete, you'll find that their role has changed to Controller. Only the Controller can start, stop, and switch the modes of the capsule. (The Owner-Controller likewise can do these tasks.)
Your role has changed to Owner. The owner can delete the capsule and revoke control from the Controller. Click on the "revoke control" button to resume Owner-Controller status.
Now the collaborator again has the role of Contributor and you are Owner-Controller.
If you no longer want to share your capsule with a user, click the red 'X' button.
When they are removed, you'll see the collaborators table has returned to displaying only you as associated with this capsule.
Bring text data into your capsule.
Perform your analysis. You can follow the Use Case guides for examples of how to perform text analysis in the capsule.
If you will need more than one session to complete your research, save your interim data to the Secure Volume.
Save data to the Secure Volume
Make sure your capsule is in secure mode (see directions above if needed).
Open a terminal window in the capsule and navigate to the secure volume by typing:
Between sessions, stop the capsule via the HTRC using the web browser on your personal desktop. The next time you log in, you can restart the same capsule and continue your work.
When you are finished with your research, request to export your non-consumptive results.
When you no longer need it, delete your capsule via the HTRC.