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 Jul 12, 2016 · 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

  2. install Java 8 (if needed)

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)

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

    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.

More details below.

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