Difference between revisions of "ViSUS Docker Deployment"

From
Jump to: navigation, search
(Example of using precompiled mod_visus)
(Use ViSUS convert from the Docker container)
(17 intermediate revisions by the same user not shown)
Line 5: Line 5:
  
 
To log in from your terminal:
 
To log in from your terminal:
 
+
<syntaxhighlight lang="bash">
<pre>docker login
+
docker login
 
Username: your_username
 
Username: your_username
Password: XXXX</pre>
+
Password: XXXX
 +
</syntaxhighlight>
  
 
Now pull the ViSUS image:
 
Now pull the ViSUS image:
docker pull visus/visus
+
<syntaxhighlight lang="bash">
 +
docker pull visus/visus
 +
</syntaxhighlight>
  
 
This image contains:  
 
This image contains:  
Line 17: Line 20:
 
* configuration files (see [[ViSUS configuration file]])
 
* configuration files (see [[ViSUS configuration file]])
 
* a simple 2D web viewer  
 
* a simple 2D web viewer  
* some tools to convert data (see [[ViSUS Convert]).
+
* some tools to convert data (see [[ViSUS Convert]]).
  
 
Run the image:
 
Run the image:
 +
<syntaxhighlight lang="bash">
 
  docker run -it --rm -p 8080:80 visus/visus
 
  docker run -it --rm -p 8080:80 visus/visus
 +
</syntaxhighlight>
  
 
Check if the server is running:
 
Check if the server is running:
curl -v "http://localhost:8080/mod_visus?action=list"
+
<syntaxhighlight lang="bash">
 +
curl -v "http://localhost:8080/mod_visus?action=list"
 +
</syntaxhighlight>
  
 
You will get a list of the current datasets on the server.
 
You will get a list of the current datasets on the server.
Line 29: Line 36:
 
=== Content of the image ===
 
=== Content of the image ===
  
This image contains folders that contains configuration and utilities.
+
This image contains folders with configuration files and utilities.
Those folder are under /home/visus:
+
The folders of interest are under /visus:
 
* '''config''', it contains the visus server.config (see [[ViSUS configuration file]])
 
* '''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]])
 
* '''apache2''', it contains the apache2 config files that you can use for security settings (see [[ViSUS Server]])
Line 37: Line 44:
 
The user can map those folders locally and edit them adding:
 
The user can map those folders locally and edit them adding:
  
<code>-v local_directory:docker_directory</code>  
+
<syntaxhighlight lang="bash">
 
+
-v local_directory:docker_directory
when you run you docker image. Your run command to mount all the folders to local directories will become as following:
+
</syntaxhighlight>
docker run -d -p 8080:80 -v $PWD/config:/home/visus/config -v $PWD/apache2:/home/visus/apache2 -v $PWD/viewer:/home/visus/viewer visus/visus
 
 
 
=== 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:
 
[[File:2dwebviewer.png|300px]]
 
 
 
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
 
  
== Example of using precompiled mod_visus ==
+
when you run you docker image.
  
Create 'server.config' file (replace 2kbit1 with your dataset name):
+
== 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]].
  
<pre>cat &lt;&lt;EOF &gt; server.config
+
If you have already a [[ViSUS configuration file]] that you want to use, you can run the container as following:
&lt;?xml version=&quot;1.0&quot; ?&gt;
+
<syntaxhighlight lang="bash">
&lt;visus&gt;
+
docker run -d -p 8080:80 -v $PWD/config:/visus/config visus/visus
  &lt;dataset name='2kbit1' url='file:///home/visus/dataset/2kbit1/visus.idx' permissions='public'/&gt;
+
</syntaxhighlight>
&lt;/visus&gt;
 
EOF</pre>
 
Create Dockerfile:
 
  
<pre>cat &lt;&lt;EOF &gt; Dockerfile
+
and edit the '''visus.config''' file (see [[ViSUS configuration file]]).
FROM visus/mod_visus
 
COPY server.config /home/visus/server.config
 
EOF</pre>
 
Build mod_visus docker image:
 
  
<pre>docker build -t visus/my-server .</pre>
+
'''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:
Run the image mounting a host volume:
+
<syntaxhighlight lang="bash">
 +
chmod 766 /path/to/your/server.config
 +
</syntaxhighlight>
  
<pre>docker run -it --rm -p 8080:80 --volume=&quot;c:/visus_dataset/2kbit1:/home/visus/dataset/2kbit1&quot; visus/my-server </pre>
+
Making the configuration file writable will allow to add datasets dynamically using the action ''add_dataset'' (see [[ViSUS Server]]).
Test if it works:
 
  
<pre>wget &quot;http://localhost:8080/mod_visus?action=readdataset&amp;dataset=2kbit1&quot;</pre>
+
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:
 +
<syntaxhighlight lang="bash">
 +
docker run -d -p 8080:80 -v $PWD/config:/visus/config -v $PWD/apache2:/visus/apache2 visus/visus
 +
</syntaxhighlight>
  
== Use ViSUS convert from docker ==
+
== Convert your data in IDX using the Docker deployment ==
  
The ViSUS tools executables (see [[ViSUS Convert]]) are contained in the image under <code>/usr/local/visus/bin</code>.
+
The ViSUS tools executables (see [[ViSUS Convert]]) are contained in the container under <code>/usr/local/visus/bin</code>.
  
 
For example, if you want to use the tools to convert a raw dataset using your docker deployment you can do it as follow.
 
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:
 
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
+
<syntaxhighlight lang="bash">
 +
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
 +
</syntaxhighlight>
  
 
Check that your container is running correctly (using <code>docker ps</code>) and take note of the ''Container ID''.
 
Check that your container is running correctly (using <code>docker ps</code>) and take note of the ''Container ID''.
  
 
Now run a bash session on this container using:
 
Now run a bash session on this container using:
docker exec -it <id_from_docker_ps> /bin/bash
+
<syntaxhighlight lang="bash">
 +
docker exec -it <id_from_docker_ps> /bin/bash
 +
</syntaxhighlight>
  
 
From this bash session you can use your ViSUS converter to convert your data (just mounted in the container) as described in [[ViSUS Convert]].
 
From this bash session you can use your ViSUS converter to convert your data (just mounted in the container) as described in [[ViSUS Convert]].
  
== Example of creating a test david_subsampled server ==
+
== Experimental: Web Viewer ==
  
Create 'server.config' file:
+
You can preview and navigate you data on the server using the webviewer using your browser at the URL: http://localhost:8080
  
<pre>cat &lt;&lt;EOF &gt; server.config
+
Here is a picture of the viewer:
&lt;?xml version=&quot;1.0&quot; ?&gt;
+
[[File:2dwebviewer.png|300px]]
&lt;visus&gt;
 
  &lt;dataset name='david_subsampled' url='file:///home/visus/dataset/david_subsampled/visus.idx' permissions='public'/&gt;
 
&lt;/visus&gt;
 
EOF</pre>
 
Create Dockerfile:
 
  
<pre>cat &lt;&lt;EOF &gt; Dockerfile
+
With the commands on the bottom bar you can:
FROM visus/mod_visus
+
* change server
COPY server.config /home/visus/server.config
+
* set a slice (if using a 3D dataset)
RUN set -x \
+
* set a timestep
  &amp;&amp; apt update \
+
* set palettes and min-max range
  &amp;&amp; apt install -y curl \
+
* choose a field of the selected dataset
  &amp;&amp; cd /home/visus/dataset \
 
  &amp;&amp; curl http://atlantis.sci.utah.edu/download/david_subsampled.tar.gz -o temp.tar.gz \
 
  &amp;&amp; tar xvzf temp.tar.gz \
 
  &amp;&amp; rm -f temp.tar.gz \
 
  &amp;&amp; chown -R www-data /home/visus/dataset \
 
  &amp;&amp; chmod -R a+rX  /home/visus/dataset 
 
EOF</pre>
 
Build mod_visus docker image:
 
 
 
<pre>docker build -t visus/david_subsampled .</pre>
 
Run the image mounting a host volume:
 
 
 
<pre>docker run -it --rm -p 8080:80 visus/david_subsampled </pre>
 
Test if it works:
 
 
 
<pre>wget &quot;http://localhost:8080/mod_visus?action=readdataset&amp;dataset=david_subsampled&quot;</pre>
 
== Some tricks ==
 
 
 
To debug mod_visus (example: to check Apache log files):
 
 
 
<pre>docker run -ti -p 8080:80 --entrypoint=/bin/bash visus/mod_visus -s
 
/usr/local/bin/httpd-foreground.sh</pre>
 
To run an interactive 'clean' ubuntu (or whatever):
 
 
 
<pre>docker run -ti -p 8080:80 --entrypoint=/bin/bash ubuntu:16.04 -s</pre>
 
If you want to remove all old docker images and containers (and you know what you are doing!)
 
  
<pre>docker rm  -f $(docker ps  -a -q)
+
Note: this component is experimental and under development.
docker rmi -f $(docker images -q)</pre>
 

Revision as of 18:40, 5 June 2018

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:

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.

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: 2dwebviewer.png

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.