My Very Own Voyant – DH2014 in Lausanne

This page is outline for the DH 2014 Workshop My Very Own Voyant: From Web to Desktop Application (PDF).

0. Introductions

Where we introduce ourselves and our experience with Voyant-Tools.

  • Have you used Voyant-Tools?
  • What do you hope to learn?
  • Outline of what we will accomplish

1. Installing and running VoyantServer locally

Where you install VoyantServer on your laptop and run it.

Note: It’s best to click the Stop Server button in VoyantServer after you are finished or you may leave processes running.

2. A brief tour of Voyant

Where those unfamiliar with Voyant get a brief tour.

3. VoyantServer settings

Where you learn about controlling VoyantServer.

Managing data (corpus indices)

  • Where are corpus indices cached?  By default data is stored in a temporary directory that is specified by your operating system. Data in that directory should persist when you start and stop VoyantServer, but it may be cleaned out by your operating system when you restart your machine.
  • The easiest way to specify an alternate location, one where the data are more likely to survive a machine restart, is to create a new, empty directory called data in the same folder as where VoyantServer.jar is located.
  • You can also set another location for your data by providing a path to an existing parent folder in the server-settings.txt file. Here is an example:

data_directory = /Users/grockwel/Documents/VoyantServerData

Modifying a Corpus ID/Name

Voyant Tools automatically assigns an ID/name to a corpus, a generated value like 1404362954425.942. After creating a corpus you can see the id/name by clicking the Export icon and producing a URL.

You can change the corpus id/name, but it should be considered an advanced operation. There are two steps:

  1. In your data directory there’s a folder named trombone3_0 which contains individual folders for each corpus. The first step is to find the folder that corresponds to your corpus and rename the folder to the new corpus id/name that you wish to use (it’s best to use a reduced character set such as alphanumeric characters, dots and hyphens)
  2. In the corpus folder there’s a file named corpus-metadata.xml – open it with an XML or text editor and modify the entry that is below the id entry, near the top of the file. Save the file, and the corpus should now be available with the new corpus id/name in the URL.

Corpus Metadata


Handling large corpora

  • For larger copora (>10 MB) you can increase the memory of VoyantServer (set the value in megabytes such as 1024, 2048, 4096, etc.). Remember to stop and restart.

4. Confidentiality

  • Using VoyantServer on confidential information.
  • How to make sure VoyantServer can’t be accessed.

5. Setting up a public server

  • How to run VoyantServer for others.
  • Deploying as a Tomcat application.

Deploying as a Tomcat application


VoyantServer ships with a compliant Java Servlet web application that can be deployed under different servlet containers, such as Apache Tomcat.  Here are some steps:

  • download Tomcat (like the core version of Tomcat 7 – the tar.gz file is recommended for Mac to preserve executable file permissions)
  • uncompress the archive (usually double-clicking on the file)
  • copy the _app folder from VoyantServer to the webapps folder in the Tomcat folder (see image below) – be sure to copy and not move the folder (on Mac you can hold the option key while dragging the folder)
  • rename the _app folder  to voyant
    • it’s actually not necessary to rename the folder, but then the URL would be something like
    • you can also make the application run in the root of the server by deleting the existing ROOT folder and renaming _app to ROOT – the the URL is something like http://127.0.01/
  • now start Tomcat by running bin/ from the Tomcat folder (this is typically done on the command-line, you can read the RUNNING.txt file in the Tomcat folder for more information)
  • usually you can then visit

By default the data will be stored in the temp directory in the Tomcat folder (which, despite its name, shouldn’t disappear during Tomcat or machine startup). This and many other settings can be tweaked, but it’s best to look at the Tomcat documentation.

6.0 Exporting and Skinning

If we have time we will now show you how you can experiment with other Voyant Tools like ResoViz.

  • After loading a text (like you can choose the Export button and use “a URL for a different tool/skin and current data” – You can now experiment with different tools not available in the standard skin. Try ResoViz.
  • You can also try a different skin. Experiment with the skins and try the Skin Builder.

7.0 For After the Workshop

Try Voyant on a text or corpus of your own after the workshop.

  1. Find or assemble a text of your own.
  2. Try studying it with Voyant.
  3. Experiment some more with the advanced features like the Exporting to a different skin. Try opening your corpus in the Skin Builder and developing your own skin.
  4. We are developing a version called Voyant Notebooks that has a literate programming interface where you can program with Voyant. This will allow you to keep a notebook of your analysis.

Staying in touch

If you want to be kept up to date on VoyantServer you can:

  • Ask to be added to a Google group to which we will send occaisional posts: (Note: this is a broadcast list not a discussion list.)
  • You can follow Voyant on Twitter @VoyantTools

To find and clean texts see:

Finding Texts:

Aggregating and Cleaning Texts:

8.0 Other Tools

What other tools are there out there? See TAPoR 2.0 for a growing list of tools.