Skip to content
This repository has been archived by the owner on Jun 15, 2021. It is now read-only.

Running as a Shared Server

Jump to bottom
Stéfan Sinclair edited this page Mar 30, 2017 · 21 revisions

Although Voyant Tools is available as a web application that can be deployed in an existing container (like Tomcat or Jetty), VoyantServer makes it convenient to run Voyant Tools independently.

Preparing the Server

VoyantServer has relatively minimal needs, but it requires at least Java 8 and we recommend at least 2GB of RAM. In Ubuntu 16+ Java 8 should already be the default, but here are some instructions for Ubuntu 14 or 15 (and of course this might serve for different distributions with slight modifications).

  1. create a new server instance

If you don't have one already and make sure it's up-to-date:

sudo apt-get update
sudo apt-get upgrade
sudo apt-get dist-upgrade`
  1. install Java 8 (if needed)

For Ubuntu 16+ you should already have Java 8, you can confirm this:

java -version

To install Java 8+ for Ubuntu 15+, this should suffice:

sudo apt-get install openjdk-8-jre-headless

For Ubuntu 14, you may need to do this:

sudo add-apt-repository ppa:webupd8team/java -y
sudo apt-get update
sudo apt-get install oracle-java8-installer
  1. install unzip

(If needed.)

sudo apt-get install unzip
  1. download and unzip the latest release (or other, the file and directory names may be different)

Note the zip file below is for an older release, be sure to copy the URL from the latest release!

curl -OL https://github.com/sgsinclair/VoyantServer/releases/download/2.1/VoyantServer2_1.zip
unzip VoyantServer2_1.zip
cd VoyantServer2_1

  1. tweak the server settings

    nano server-settings.txt

  • for simplicity change the port from 8888 to 80 (if desired)
  • change the amount memory in MB (at least 1024, ideally 4096 or more, depending on available RAM)

  1. launch the server (using the embedded Jetty server)

    sudo java -jar VoyantServer.jar --headless=true &

We launch this using sudo (because it's using the restricted port 80) and we detach the process from the current console.

A Slightly More Robust Variant

VoyantServer is fairly robust but it can crack under pressure, especially with multiple concurrent users (like in a workshop or class). One possible solution is to have a cron job that checks the health of the server every minute and restarts the server if need be. The instructions below assumes that the main username is "ubuntu" (with sudo privileges), but of course things can be tweaked as needed depending on your setup.

Create a Health Check

We will create a script called checkHealth.sh in our home directory (/home/ubuntu), the location doesn't matter, but we'll need the exact directory name later when we add a cron job. Note that there are a few assumptions about server port (80), corpus available (austen), location of the VoyantServer (/home/ubuntu/VoyantServer2_2), etc.

#!/bin/sh
# we will make a simple call to the local server and give it up to one second to respond
# (assuming port 80 and the built-in austen corpus)
HTTP_STATUS=$(curl -m 1 -s -o /dev/null -w "%{http_code}" "http://localhost/trombone?corpus=austen&tool=corpus.CorpusTerms&limit=1&withDistributions=true&noCache=1")
if [ $HTTP_STATUS -ne 200 ]; then
    pkill java
    # note the full location of java and the location of the server app (may need to be changed)
    /usr/lib/jvm/java-8-openjdk-amd64/jre/bin/java -Dfile.encoding=UTF-8 -Xmx2048m -classpath /home/ubuntu/VoyantServer2_2/VoyantServer.jar org.aw20.jettydesktop.rte.JettyRunTime 80 /home/ubuntu/VoyantServer2_2/_app 34000 > /dev/null 2>&1 &
    # here's a variant that logs to a file:
    # /usr/lib/jvm/java-8-openjdk-amd64/jre/bin/java -Dfile.encoding=UTF-8 -Xmx2048m -classpath /home/ubuntu/VoyantServer2_2/VoyantServer.jar org.aw20.jettydesktop.rte.JettyRunTime 80 /home/ubuntu/VoyantServer2_2/_app 34000 >> /home/ubuntu/VoyantServer2_2/logs.txt 2>&1 & 
    today=`date '+%Y_%m_%d__%H_%M_%S'`
    echo "VoyantServer restarted "+$today >> /home/ubuntu/restarts.txt
fi

We want to make this script executable:

chmod 755 checkHealth.sh

Above we're calling the full command for VoyantServer, we're not using VoyantServer.jar. You can determine the full command your configuration is using by launching the server as per the first set of instructions:

sudo java -jar VoyantServer.jar --headless=true &

And then looking at the full command that was launched:

ps aux | grep java

Creating a Cron Task

Now we want to call this every minute by editing the crontab:

sudo nano /etc/crontab

And pasting in this line which says run this as root every minute:

* * * * * root /home/ubuntu/checkHealth.sh

That's it! If you want to test if it worked, just stop your server

sudo pkill java

And wait a minute to see if it restarted (you can try the web browser or look in /home/ubuntu/restarts.txt).

This technique has the added bonus of restarting VoyantServer automatically if your server ever needs to reboot.

Starting VoyantServer from the UI Console

Starting VoyantServer from the command line

The below presumes you've installed and configured VoyantServer, and that you've configured your environment (for instance, to ensure access to the VoyantServer port is possible). It also presumes you are operating on a system where you have command-line access and that is Unix-like (including Linux and Mac OS X).

cd /path/to/voyant
sudo nohup java -jar VoyantServer.jar --headless=true &
sudo tail -f nohup.out

For those new to command-line operation, we'll break that down. (It's completely OK if you don't consider yourself strictly "new" but still want to read the explanation below.)

sudo

Execute this command as the superuser or as another user (Learn more about sudo)

nohup

Don't interrupt this process when this terminal session ends. (Learn more about nohup)

java -jar VoyantServer.jar

Run Java on a Java Archive file, specifically the VoyantServer JAR. (Learn more about JAR files)

--headless=true

Run Voyant Server without needing a GUI

&

Run this process in the background so this terminal session can then be used to do other things. This is not strictly necessary, but it allows you to SSH to your server, start Voyant Server, and go on to other actions without needing to start a new SSH session.

sudo tail -f nohup.out

Watch the contents of nohup.out, the file that will receive all the log information that would otherwise have been visible in the console, starting with the last 10 lines of the file and updating it as it is written to. This is not necessary, but helps because you will see the message indicating that Voyant Server has started up completely. Use Ctrl+c to stop tailing the file.

After running Voyant Server for a while (which length of time depends greatly on how active is your use of your installation), the nohup.out file will get pretty big. Check in on it from time to time, backing it up and starting a new clean file. (You will need to be considerate about how you back it up and start a new file so you don't interrupt work on the Voyant Server, of course.)

Starting VoyantServer Automatically

If you want to start Voyant Server automatically (at server boot or keyed to something else), you will need to tie the startup instructions above into your operating system's startup items.

CentOS

The Easy Way

The usual caveats (such as "the below works for me but might not for you") apply here.

Create a file named voyant.sh,and set the permissions to 755. The location should be 1) where you'll remember the file and 2) where the root user can access it. The second requirement may seem unnecessary to articulate, but we don't know what changes you've made to your system or what restrictions your host has put on.

In that file, save the following text, replacing /path/to with your actual path to Voyant Server.

cd /path/to/voyant
nohup java -jar VoyantServer.jar --headless=true &

Then, using

sudo crontab -e

add

@reboot /path/to/voyant.sh

to your cron jobs and save.

Naturally, you should test reboot to be sure it works for your environment.

Clone this wiki locally