##############
Docker Support
##############

The HOOPS Communicator package and installer contain a :doc:`Getting Started </overview/quickstart>` guide, which allows you to easily set up HOOPS Communicator on a server to convert and view models quickly without much additional setup. This is convenient for demonstration and evaluation purposes, but for production deployments, many customers will want a more secure and robust solution, such as Docker containers.

We offer several Docker templates for the major components of HOOPS Communicator. They can be found in our `BitBucket repo <https://bitbucket.org/techsoft3d/communicator-docker/src/master/>`_ for all HOOPS Communicator versions starting with version 2020.


Basic configuration
===================

You will need to have Docker installed. The recommended way is to use `docker-install <https://github.com/docker/docker-install>`_. Add your user to the Docker group using the following command::

	sudo usermod -aG docker <your user name>

These changes may not take effect until your next login as the user added above. Once Docker is installed the following steps can be used to build Communicator images:

#. Extract your Communicator package that was downloaded from your `Manage Account <http://manage.techsoft3d.com>`_ portal
#. Copy the contents of the folder corresponding to your Communicator version into the root of the package
#. Open a new terminal in the root of the packages
#. Build the Docker files by running the appropriate commands


Extending the containers
------------------------

While the provided images work out of the box, they are meant to be a point of departure for integrating HOOPS Communicator into your workflow. In most cases, you will want the containers to be more self-contained and not rely on paths from the host machine.

A common modification to the base Communicator containers is to build in logic for interacting with file storage. In the case of viewing, this would involve pulling the model out of the store before starting the SC Streaming Server. In the case of conversion, source files would be retrieved and processed by HOOPS Converter. After processing, the files would be pushed to the file store. 


HOOPS Containers with AWS
-------------------------

Overview
........

The provided Docker files allow for out-of-the-box usage of HOOPS Converter and the Stream Cache Server in both CSR and SSR mode. This document will help you modify and supplement those containers with additional code to make them work in the context of Amazon Web Services.
Running the HOOPS Communicator components in containers provides a sandbox environment that simplifies running components, as well as providing automated cleanup of temporary files when a session closes, or in the unlikely event of a system failure.

HOOPS Converter
...............

:doc:`HOOPS Converter </prog_guide/data_import/cad_conversion/converter_app/converter-application-overview>` is used to convert CAD files into the :doc:`Stream Cache </prog_guide/viewing/data_model/stream_cache/overview>` format so that they can be efficiently streamed and viewed using the :doc:`Web Viewer </prog_guide/viewing/overview>`. Depending on the size and complexity of the model, this process can take anywhere from a couple of seconds to many minutes. For larger files, this can push you over the limits allowed by AWS Lambda.

A containerized approach to handle large file conversion can make use of the `Elastic Container Search <https://aws.amazon.com/ecs/>`_. ECS is a container orchestration service that can be used to run containers using several backends. Using the EC2 backend, the system will launch containers from a cluster of running instances that you create and can be scaled using an autoscaling group. A serverless option is provided using the `Fargate <https://aws.amazon.com/fargate/>`_ backend. AWS Fargate will automatically find available AWS resources to run your container while you manage and scale an EC2 cluster. There are spot options available with Fargate as well.

When running conversions from within your container, you will need to write application code to perform the necessary steps for file conversion. This will most likely include the following steps:

#. Retrieving the source file(s) from S3 object storage
#. Running HOOPS Converter on the files
#. Updating a database with conversion details
#. Uploading the result of the conversion to a Cloud storage solution such as S3, EFS, etc.


Stream Cache Streaming Server
.............................

The SC streaming server is designed to allow the user to interact with large CAD models as quickly as possible. The ephemeral nature of viewing sessions lends itself to a different container strategy than we could take with file conversion. Orchestrating containers using ECS takes a relatively long amount of time because the container must first be provisioned before finally becoming active. This time delay will in most cases lead to a suboptimal user experience.

A containerized approach to running SC streaming servers requires you to manually start the container on your EC2 instances when requests for viewing sessions come into the server. To facilitate this behavior, an AMI is created, which has the Docker runtime installed. A web application is also running on the server, which will listen and process requests for viewing sessions. This application should handle any authentication or business logic associated with creating a viewing session. It will then create a container using the Docker daemon running on the local EC2 instance. Scaling this scenario can be accomplished by using an EC2 autoscaling group tied to `CloudWatch <https://aws.amazon.com/cloudwatch/>`_ alerts.

While running the SC streaming server within your container, you will need to write application code to perform the necessary steps for WebSocket streaming. This will most likely include the following steps:

#. Retrieving the stream cache model(s) from storage solution S3 or EFS
#. Start the SC streaming server

At this point, the spawning application would begin proxying the incoming connection to the container.

.. note::
	
	The SC streaming server has a command-line option for :doc:`liveliness </prog_guide/servers/stream_cache_server/liveliness-pinging>` updates. If a value for this option is specified, the server will make a POST request indicating that the server is fully initialized and ready to start streaming.
