instant3Dhub License Server#

Read First#

The instant3Dhub License Server needs to be accessible by the servers instant3Dhub is running on. The License Server cannot be run in container environments as it is bound to a host machine. There are two options for storing data (you need to use PostgreSQL 14):

We recommend an externally managed PostgreSQL in order to avoid data loss.

Installation#

First start by installing and setting up PostgresSQL and obtain a connection string.

Using local PostgreSQL instance#

We assume that no instant3Dhub version 2 PostgreSQL installation is running on the same machine. If this is the case the port and socket directory used by the license database Postgres cluster must be changed from 5433 to another port, for example to 5435 and /var/run/instant3DhubLicensePgsql.

We recommend PostgreSQL version 14, but require a minimum version of 9.5. The minmum version may change in the future, so we recommend installing the highest version available in order to avoid time consuming upgrades.

For RedHat based systems, we recommend using the official PostgreSQL repository to download packages. This guide will exemplify the installation using RedHat.

First, add the official PostgreSQL repository to the package manager:

yum -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-$(rpm -E %{rhel})-x86_64/pgdg-redhat-repo-latest.noarch.rpm
yum -y update

Next, install PostgreSQL 14:

yum install -y postgresql14
yum install -y postgresql14-server
yum install -y postgresql14-contrib

Initialize and check the PostgreSQL-service (must be active and running):

/usr/pgsql-14/bin/postgresql-14-setup initdb
systemctl start postgresql-14
systemctl enable postgresql-14
systemctl status postgresql-14

Warning

If Postgres-service cannot be launched then set the correct permissions for PostgreSQL from 0755 to 2777:

sed -i 's/postgresql 0755 postgres postgres - -/postgresql 2777 postgres postgres - -/g' /usr/lib/tmpfiles.d/postgresql-14.conf

Now you may configure a connection string or use the defualt one (for details see Configuration of Postgres connection string)

Now you may configure a connection string or use the defualt one (for details see Configuration of Postgres connection string)

Using remote PostgreSQL instance#

In case you have a PostgreSQL instance that is running on a differnt machine or provisioned externally, all you need is to configure the License Server to use the remote PostgreSQL instance by providing a connection string (see Configuration of Postgres connection string). The License Server will setup or migrate required tables on startup. To start the server, make sure to use the systemd unit file which does not depend on a local postgres instance:

systemctl start instant3DhubLicenseServerRemoteDB.service
systemctl status instant3DhubLicenseServerRemoteDB.service

Configuration of Postgres connection string#

Initially Postgres service sets up a database postgres with a username postgres and a password postgres, which is being used as the default connection by the License Server as follows postgresql://postgres:postgres@localhost:5432/postgres?sslmode=disable (see License Server configuration). You may configure a new connection according to the pattern postgres://{NEW_USER}:{PASSWORD}@{NEW_HOSTNAME}:{PORT}/{NEW_DATABASE}?sslmode=disable (described here) To create a new database with a new user please refer to the official.

Install the License Server#

The instant3Dhub License Server is installed from RPM files. The installation requires the OS dependent License Server package:

  • CentOS 7 : instant3Dhub-licenseServer-CentOS-Linux-7-x64*.rpm

  • SLES-12.3 : instant3Dhub-licenseServer-SLES-12.3-x64*.rpm

  • Fedora 23 : instant3Dhub-licenseServer-Fedora-23-x64*.rpm

  • Fedora 29 : instant3Dhub-licenseServer-Fedora-29-x64*.rpm

The latest installation files and a changelog can be found here.

Note

For OS where is the Debian package management tools are used installation process of the License Server and a Postgres service instance differs. Please refer to the page with example for Ubuntu (instant3Dhub License Server on Ubuntu).

First download the latest version of the License Server for your OS, for example:

wget https://repo.threedy.io/licenseserver/23.1/instant3Dhub-licenseServer-CentOS-Linux-7-x64.23.1.rpm

And install the package:

yum install -y ./instant3Dhub-licenseServer-CentOS-Linux-7-x64.23.1.rpm

License Server configuration#

Before starting the license server it must be properly configured. Configuration is provided by creating a configuration file at the /opt/instant3Dhub.custom/license_config.yml. Below is a sample file with available options and their defaults. If no file exists, the defaults seen below will be used:

# whether to use the BIOS ID of the current machine when performing host checks
use-bios-uuid: false

# interface and port to listen on
address: 0.0.0.0:8200

# log level to use. options: fatal panic error warning info debug trace
log-level: warning

# location of the license file
licenseFile: /opt/instant3Dhub.custom/license.xml

# location of tls certificate
tls-cert:

# location of tls private key
tls-key:

# postgres backend options
postgres:
  # connection string describing the postgres location and user. the given
  # user must have permissions to create schemas, tables and stored procedures.
  # expected format is the URI format described here: https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING
  connection-string: postgresql://postgres:postgres@localhost:5432/postgres?sslmode=disable

  # user to use once migrations are complete. this user also receives table write permissions during migrations
  # by default the user from the connection string is also used during runtime.
  runtime-user:

  # password for the runtime user to allow switching to this user once migrations are complete
  # this value must be given if a runtime user is also provided
  runtime-password:

Note

You may configure your connection instead of using the default one (for details see Configuration of Postgres connection string).

Start the License Server#

systemctl restart instant3DhubLicenseServer{RemoteDB}.service
systemctl status instant3DhubLicenseServer{RemoteDB}.service

The status should now be active.

In default configuration this service exposes 8200.

An address to the License Server must be placed inside the setup file of your instant3Dhub deployment.

Acquire License#

Licenses are bound to a single host when running in offline mode. We require a HostID and initial usage export to generate a new license.

This can be acquired via either the command line or the web interface:

  • Command line: curl http://localhost:8200/usage/export -o i3dh-usage-export.zip

  • Web interface: http://your.license.server:8200/usage/export

Please provide your threedy contact or if you have no valid license agreement yet sales@threedy.io with this output to start the license key aquisition process. In return a license file will be provided to you.

Warning

The hostID depends on the hardware configuration of your machine such as the network adapter and hard drive. In some virtualized environments, the hardware configuration can be dynamic by default and it might changes when restarting a VM. Therefore, please make sure that is not the case in your setup as this will result in a changing HostID.

License file placement#

A received license file must be placed to:

/opt/instant3Dhub.custom/license.xml

When using this method, please restart the license server to apply the new license.

Alternatively it can also be uploaded via the web interface of the license server, in which case a restart is not necessary.