How To: Install and Build Voyager

Installation

This document describes how to install a local development server, and build the source code for development and production.

If you are just interested in using Voyager on your site and have no need to host or customize it, please take a look at How To: Embed a model on your site.

The Voyager development environment can be run either directly in a suitable Linux environment (tested on Ubuntu Server 18.04), or in a Docker container. If you already have Docker and Docker Compose installed, we highly recommend installing in a container.

Prerequisites

Operating system for direct installation: Linux only (tested on Ubuntu server 18.04).

Before cloning the Github project, please install the following tools

Node.js - required
Docker - required for installation in a Docker container
Docker Compose - required for installation in a Docker container

Now create a project folder and clone the project from Github. Make sure not to forget the --recurse-submodules option, this also clones the required submodules.

mkdir <my_project_dir>
cd <my_project_dir>
git clone --recurse-submodules https://github.com/smithsonian/dpo-voyager .

Copy and rename the .env.template file:

cp .env.template .env

Now edit the environment variables in .env in your editor of choice to reflect your local configuration. To edit using vim enter:

vim .env

Make sure you change the server port if necessary.

Dockerized environment

For development, if you have Docker and Docker Compose installed, you can run the development server in a container. To build the Docker image and start the container with the development server, run

npm run up

This also watches all source folders for changes and triggers the Typescript compilation and Webpack build whenever source code changes are detected.

Once you are done, shut down the development server.

npm run down

To open a shell on the running server container, enter

npm run bash

Manual builds for development and production

First start the development server with npm run up, then connect to the container with npm run bash. On the container shell, enter

npm run build-dev       # triggers a development build
npm run build-prod      # triggers a production build

The development build preserves source code comments and comes with source code maps
The production build generates minified scripts and CSS

Note that you must run the build commands from within the docker container.
Build output can be found in the project’s dist folder, see below.

Installation on Linux, without Docker

Note: Due to the variety of operating systems, we strongly recommend to run the dockerized environment. This guarantees a standardized development environment.

Without Docker, you need to install the NPM package dependencies manually.

npm install

Now you are ready to build the project. The following command builds the development server.

npm run build-server

If you want to specifically create a development or production build, use the following commands.

npm run build-dev
npm run build-prod

Location of build output

Build output can be found in the project’s dist folder. It’s content after both prod and dev builds have been run:

css/                       # style sheets
fonts/                     # web fonts
images/                    # images and logos
js/                        # client-side Javascript for all applications
favicon.png
voyager-explorer.html      # HTML page displaying Voyager Explorer, production build
voyager-explorer-dev.html  # HTML page displaying Voyager Explorer, development build
voyager-mini.html          # HTML page displaying Voyager Explorer Mini, production build
voyager-mini-dev.html      # HTML page displaying Voyager Explorer Mini, development build
voyager-story.html         # HTML page displaying Voyager Story authoring tool, production build
voyager-story-dev.html     # HTML page displaying Voyager Story authoring tool, development build

Introduction

Explorer