ViSUS Docker Deployment

Quick start

Start your Docker and login into your account. If you don't have installed follow these instructions: Docker Documentation

To log in from your terminal:

docker login
Username: your_username
Password: XXXX

Now pull the ViSUS image:

docker pull visus/visus

This image contains:

• the ViSUS Server
• configuration files (see ViSUS configuration file)
• a simple 2D web viewer
• some tools to convert data (see ViSUS Convert).

Run the image:

docker run -it --rm -p 8080:80 visus/visus

Check if the server is running:

curl -v "http://localhost:8080/mod_visus?action=list"

You will get a list of the current datasets on the server.

Content of the image

This image contains folders with configuration files and utilities. The folders of interest are under /visus:

• config, it contains the visus server.config (see ViSUS configuration file)
• apache2, it contains the apache2 config files that you can use for security settings (see ViSUS Server)
• visus, it contains visus tool (see ViSUS Convert) to convert data to IDX format

The user can map those folders locally and edit them adding:

-v local_directory:docker_directory

when you run you docker image.

ViSUS Server for NetCDF data

An addition on-demand conversion service for NetCDF datasets is available in the "ondemand" Docker container.

To try it, pull the ViSUS on-demand image:

docker pull visus/ondemand

This container provides three services:

• the ViSUS Server
• conversion service (i.e., currently limited to NetCDF datasets)
• a simple Web viewer

How to run the Containter

You need to specify few simple settings:

• the port you want to use for the conversion service (internal 80)
• the port you want to use for the webviewer and data server (internal 42299)
• the folder containing the files to serve/convert (i.e., NetCDF files), this will be mapped to "/data/xml" in the container
• a folder to use for caching the multiresolution data for streaming, this will be mapped to "/data/idx" in the container

Quick start with some demo data:

# create directory for your input data
mkdir -p $PWD/nc
# create directory for your cache
mkdir -p $PWD/idx

# download a sample NetCDF dataset
wget https://www.dropbox.com/s/jnhptd5vswaurem/test2d.nc -O ./nc/test2d.nc

Run the container:

docker run -it -p 80:80 -p 42299:42299 -v $PWD/nc:/data/xml -v $PWD/idx:/data/idx visus/ondemand

In this run command we mapped:

• port 80, used in the container for the data streaming and webviewer services
• port 42299, used in the container for the NetCDF data conversion service

How to visualize your data on the server

Go to the On-demand test page: http://localhost/ondemand.php. Note: replace "localhost" with your server name and port if you are running with custom settings.

In this page you will find the list of *.nc contained in the folder you provided. You can click on the corresponding "View" button to visualize your data. Note: if the dataset has not been already converted the request could take a few second since it will be converting on-demand.

How to customize the list of datasets on your server

The list of dataset that the server exposes are contained in the ViSUS configuration file.

If you have already a ViSUS configuration file that you want to use, you can run the container as following:

docker run -d -p 8080:80 -v $PWD/config:/visus/config visus/visus

and edit the visus.config file (see ViSUS configuration file).

Note: The server needs to be able to read and write the configuration file, so make sure that your server.config has the right privileges. For example:

chmod 766 /path/to/your/server.config

Making the configuration file writable will allow to add datasets dynamically using the action add_dataset (see ViSUS Server).

If you also want to customize the apache security (e.g. change the users) you can run the command to mount also the apache2 directory as following:

docker run -d -p 8080:80 -v $PWD/config:/visus/config -v $PWD/apache2:/visus/apache2 visus/visus

Convert your data in IDX using the Docker deployment

The ViSUS tools executables (see ViSUS Convert) are contained in the container under /usr/local/visus/bin.

For example, if you want to use the tools to convert a raw dataset using your docker deployment you can do it as follow.

Mount a folder that contains your raw data and your converted idx data as follow:

docker run -d -p 8080:80 -v /full/path/to/your/raw/:/home/visus/datasets/raw -v /full/path/to/your/idx/:/home/visus/datasets/idx visus/visus

Check that your container is running correctly (using docker ps) and take note of the Container ID.

Now run a bash session on this container using:

docker exec -it <id_from_docker_ps> /bin/bash

From this bash session you can use your ViSUS converter to convert your data (just mounted in the container) as described in ViSUS Convert.

Experimental: Web Viewer

You can preview and navigate you data on the server using the webviewer using your browser at the URL: http://localhost:8080

Here is a picture of the viewer:

With the commands on the bottom bar you can:

• change server
• set a slice (if using a 3D dataset)
• set a timestep
• set palettes and min-max range
• choose a field of the selected dataset

Note: this component is experimental and under development.