This is a development snapshot of the upcoming main version 3 of instant3Dhub.
This version includes a reduced set of features and misses functionalities that will be included in the full release version.
Obviously this should not be used in a productive environment or with sensitive data.
We value Docker-Compose as a lightweight, rapid development alternative to our Helm deploy format.
However for aspects like Scaling Security and Integration into the latest orchestration tools landscape we recommend our Kubernetes deploy format.
Here is a non-extensive list of these functionalities:
* **Stability**: Implementation and consolidation is not completed at this point and the system is in a highly experimental state. At this state it should only be used for integration testing and helping the development team by providing feedback.
* **External DB use**: The system currently only works with the packaged database containers. In a future update more configuration will be exposed.
* **Gateway integration**: Currently not included with our Docker-Compose deploy.
* **Secret Handling**: Currently access information to the local database and message queue are stored as plain-text.
* **HTTPS**: HTTPS is not supported inside the cluster or at the gateway. Even in the release version we will not recommend the use of HTTPS within the cluster, but provide a wider range of possibilities to secure the cluster access itself. Currently HTTPS can be used by adding a proxy outside of the cluster or as a sidecar on the apigw component.
* **Services**: Currently only the SharedSession and Measurement services are enabled. This means a range of functionalities will not be available in webvis and other API-libraries.
* **Security/Signatues**: The third main version instant3Dhub is designed to include security on all layers of the system like controlling the access to the management APIs, resource APIs, the services or the data that goes through the system. At this stage there are still some lose ends on the implementation side and most of these features are disabled.
* **Volumes** : Currently our Docker-Compose deploy uses local volumes. Other possiblities for data mounts will be added later.
********************************************
Installation
********************************************
The instant3Dhub Docker-Compose deployment is based on `Docker-Compose v2 <https://docs.docker.com/compose/compose-file/compose-file-v2/>`_ Files.
Requirements
============================================
* Docker: v20.10.2
* Docker-Compose: v1.25.0
Newer versions on minor level might work, but were not tested!
Overview
--------------------------------------------
The installation of instant3Dhub consists of three phases:
#. **Provisioning**: First the server and required resources need to be set up
#. **Configuration**: instant3Dhub needs to be configured to integrate correctly with the infrastructure
#. **Startup**: Finally the system is applied to the server or passed to a GitOps pipeline
Phase 1: Provisioning
--------------------------------------------
To following resources have to be provisioned to enable the cluster to run instant3Dhub
* License Server
* Image Registry
* Storage
* Database (optional)
.. _`License Server`:
License Server
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A instant3Dhub License Server needs to be accessible by the server our Docker-Compose deploy is run at.
The license server can not be run in virtualized environments. A guide on how to set up the license server can be found `here <./LICENSE_SERVER.md>`_
Image Registry
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
We encourage transfering all containers referenced by our Docker-Compose or Helm deploys into a local selfmanaged image repository.
To load the images into the registry you can use tools like `skopeo <https://github.com/containers/skopeo>`_ or `docker <https://docs.docker.com/engine/reference/commandline/cli/>`_.
The references contain an example script to fill the local image registry.
The images of instant3Dhub are provided on a public registry: `instant3Dhub-images <https://images.threedy.io>`_
**It is highly discouraged to use the public registry for direct access by the nodes!**
If you can not use an image registry, the nodes of the cluster can also be provisioned proactively. For more information see: `Pre-pulled images <https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod>`_
Storage
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
instant3Dhub via docker-compose requires a set of volumes for persistency and data exchange between services in the system.
For our Docker-Compose deploy we currently only use locally bound volumes.
The following volumes are defined inside the compose file and required to run instant3Dhub:
**DEPLOY_HOSTNAME**: This should be the address used to reach the docker-compose host. Internal components will use this address to link our exported webcomponents back to the instant3Dhub components.
**PROJECT_NAME**: Used namespace and docker component names.
**IMAGE_REGISTRY**: This should point to your own docker image registry. Container names and tags are predefined inside the script, only this IMAGE_REGISTRY part can and must be changed.
**LICENSE_SERVER_URL**: The License server must be reachable from within our containers. For more information referr `here <./LICENSE_SERVER.md>`_
**HUB_BASE_PORT**: instant3Dhub via docker-compose hosts all component ports directly to the external hosts interface. Currently we reserve a range of 400 ports for this. At a later point in development we will put these behind a gateway.
Phase 3: Startup
--------------------------------------------
Utilize the following script in ./reference/compose/compose/scripts/
invoke full.sh to initialize all compose templates and start the docker-compose deploy.
A printout should tell you how to reach webVis.
After all containers are running the system might take up to one minute to initialize correctly.
For an easy overview of the docker-compose deploy status use the watch.sh script.
@@ -12,12 +12,12 @@ This version includes a reduced set of features and misses functionalities that
Obviously this should not be used in a productive environment or with sensitive data.
Here is a non-extensive list of these functionalities:
* **Stability**: Implementation and consolidation is not completed at this point and the system is on a highly experimental state. At this state it should only be used for integration testing and helping the development team by providing feedback.
* **Stability**: Implementation and consolidation is not completed at this point and the system is in a highly experimental state. At this state it should only be used for integration testing and helping the development team by providing feedback.
* **External DB use**: The system currently only works with the packaged database containers. In a future update more configuration will be exposed.
* **Gateway integration**: Similarly currently no configuration options are available to replace the packaged gateway. Technically this is possible, even in the current version. But we can't provide support on how to correctly configure that at the moment.
* **Secret Handling**: Currently access information to the local database and message queue are stored as plain-text.
* **HTTPS**: HTTPS is not supported inside the cluster or at the gateway. Even in the release version we will not recommend the use of HTTPS within the cluster, but provide a wider range of possibilities to secure the cluster access itself. Currently HTTPS can be used by adding a proxy outside of the cluster or as a sidecar on the apigw component.
* **Services**: Currently only the SharedSession service is enabled. This means a range of functionalities will not be available in webvis and other API-libraries.
* **Services**: Currently only the SharedSession and Measurement services are enabled. This means a range of functionalities will not be available in webvis and other API-libraries.
* **Security/Signatues**: The third main version instant3Dhub is designed to include security on all layers of the system like controlling the access to the management APIs, resource APIs, the services or the data that goes through the system. At this stage there are still some lose ends on the implementation side and most of these features are disabled.
@@ -27,9 +27,9 @@ The repository is organized in the following way:
* **\*.rst**: This are the documentation files on how to use this repository and install instant3Dhub.
* **helm/**: This is a typical Helm Chart. Configuration is mainly done by editing the values.yaml.
* **compose/**: This contains another method to deploy instant3Dhub via docker-compose. Currently this is a set of scripts that prepare the environment based on the configuration set in the env.
* **reference/**: Contains auxiliary scripts to use or as an example on how to fulfill requirements
* **helm/**: This contains a pv.yml with a set of example PersistentVolume and StorageClass resource descriptors. The install.sh and uninstall.sh show how the automation with the helm cli could be automated.
* **compose/**: This contains another method to deploy instant3Dhub via docker-compose. Currently this is a set of scripts that prepare the environment based on the configuration set in the env.
* **transfer_images.sh**: This is a utility script for transfering the instant3Dhub container images to another registry, which needs to be done once on before the first deploy or an update.
