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 (recommended to use PostgreSQL 14):
We recommend an externally managed PostgreSQL in order to avoid data loss.
Warning
If upgrading the license server from version 21.4, see the upgrading section below for instructions. Upgrading from older versions requires a full reinstall. Upgrading from newer versions is done automatically.
Installation¶
The instant3Dhub License Server is installed from RPM files. Configuration is done via Ansible. If you need guidance on how to install Ansible please refer to our Ansible install guide.
Installation Package¶
The installation requires two packages, 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
and the ansible roles to install and initialize the database:
instant3Dhub-ansible-noarch-*.tgz
The latest installation files and a changelog can be found here
Fresh Installation with Ansible and Local PostgreSQL¶
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 postrgres 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 minmum 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 CentOS 7.
First, add the official PostgreSQL repository to the package manager:
sudo yum install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
Next, install PostgreSQL 14:
sudo yum install -y postgresql14-server
sudo yum install -y postgresql14-contrib
Now we will use Ansible to configure PostgreSQL for our needs. Unzip the
provided instant3Dhub-ansibledb-noarch-\*.tgz from above:
tar zxvf ./instant3Dhub-ansibledb-*.tgz
The current folder should now contain an ./ansible/PostgreSQL/ folder.
In the following documentation we assume that the License Server is installed on
the same host used as the ansible control host. For that reason the following
inventory is a localhost inventory. Create the following hosts.yml:
hubs:
hosts:
localhost:
vars:
ansible_connection: local
pgsql_version: 14
pgsql_do_install: false
pgsql_bin_directory: /usr/pgsql-14/bin
#pgsql_configure_selinux: true
Note
SELinux: if you are required to run SELinux please uncomment the
pgsql_configure_selinux part of the inventory.
Invoke the following playbooks:
ansible-playbook -i hosts.yml ./ansible/PostgreSQL/pgsql.licensedb.install.yml
ansible-playbook -i hosts.yml ./ansible/PostgreSQL/pgsql.licensedb.init.yml
This installs and initializes a PostgreSQL instance.
Fresh Installation with Remote PostgreSQL¶
Install the correct RPM for your distribution from here.
You will need to configure the license server to use PostgreSQL the remote instance by providing a 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
Install License Server¶
sudo yum install -y ./instant3Dhub-licenseServer-*.rpm
HostID generation¶
Licenses are bound to a single host. We require a HostID to provide a license. Please invoke
/opt/instant3Dhub/bin/licenseTool
The output should look similar to the following:
Current Host ID: 7bf3b23f5c6ff5a444a37f2dfc42ed34f5c470df
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.
License File placement¶
Please put the license file you received to:
/opt/instant3Dhub.custom/license.xml
Restart the License Server:
systemctl restart instant3DhubLicenseServer{RemoteDB}.service
systemctl status instant3DhubLicenseServer{RemoteDB}.service
The status should now show be active.
In default configuration this service exposes 8200 and records license data in a local PostgreSQL instance.
An address to this License Server must be placed inside the setup file of your instant3Dhub deployment.
License Server Configuration¶
Configuration can be 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: info
# 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://i3dhub:12and3@localhost:5433/instantLicense?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:
License Server Upgrades¶
Upgrades are normally painless and only require the installation of a new RPM package. The database will automatically be updated when the license server starts up the next time. Below is a list of upgrades which require manual intervention.
Upgrading from 21.4 to 22.1¶
This process is fairly involved as any version before 22.1 used PostgreSQL 9.2. Version 22.1 however requires a minmum PostgreSQL version of 9.5. In order to avoid more upgrades in the future, we recommend upgrading to the latest PostgreSQL version available. Below is the process for upgrading from PostgreSQL 9.2 to PostgreSQL 14 on CentOS 7.
First, shut down the currently running license server:
systemctl stop instant3DhubLicenseServer
systemctl stop instantHubPGDB
Next, move the internal PostgreSQL data to a new folder as the newer version will use the same directory as the old installation:
mv /var/cache/instant3Dhub3/pgsql/data /var/cache/instant3Dhub3/pgsql/data.bak
Now we are ready to install a new PostgreSQL version. First, add the official PostgreSQL repository to the package manager:
sudo yum install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
Next, install PostgreSQL 14:
sudo yum install -y postgresql14-server
sudo yum install -y postgresql14-contrib
Now we will use Ansible to configure the new version for our needs. Unzip the
provided instant3Dhub-ansibledb-noarch-\*.tgz from above:
tar zxvf ./instant3Dhub-ansibledb-*.tgz
The current folder should now contain an ./ansible/PostgreSQL/ folder.
Create the following hosts.yml:
hubs:
hosts:
localhost:
vars:
ansible_connection: local
pgsql_version: 14
pgsql_do_install: false
pgsql_bin_directory: /usr/pgsql-14/bin
#pgsql_configure_selinux: true
Note
SELinux: if you are required to run SELinux please uncomment the
pgsql_configure_selinux part of the inventory.
Invoke the following playbook to initializes a PostgreSQL instance ready to be upgraded:
ansible-playbook -i hosts.yml ./ansible/PostgreSQL/pgsql.licensedb.install.yml
Next, stop the new instance again:
systemctl stop instantHubPGDB
There is an issue with pg_upgrade starting the old and new PostgreSQL
instances during the upgrade process where the wrong command line parameters are
passed, so we need to fix this by rerouting pg_ctl through a shell script
first. We do this with the following commands:
mv /usr/bin/pg_ctl{,-orig}
echo '#!/bin/bash' > /usr/bin/pg_ctl
echo '"$0"-orig "${@/unix_socket_directory/unix_socket_directories}"' >> /usr/bin/pg_ctl
chmod +x /usr/bin/pg_ctl
Next, we run the upgrade process itself:
sudo -u instant3dhub /usr/pgsql-14/bin/pg_upgrade \
--old-datadir /var/cache/instant3Dhub3/pgsql/data.bak \
--new-datadir /var/cache/instant3Dhub3/pgsql/data \
--old-bindir /usr/bin/ \
--new-bindir /usr/pgsql-14/bin/
This should complete successfully with the following output:
Performing Consistency Checks
-----------------------------
Checking cluster versions ok
Checking database user is the install user ok
Checking database connection settings ok
Checking for prepared transactions ok
Checking for system-defined composite types in user tables ok
Checking for reg* data types in user tables ok
Checking for contrib/isn with bigint-passing mismatch ok
Checking for user-defined encoding conversions ok
Checking for user-defined postfix operators ok
Checking for tables WITH OIDS ok
Checking for invalid "sql_identifier" user columns ok
Checking for invalid "unknown" user columns ok
Checking for roles starting with "pg_" ok
Checking for incompatible "line" data type ok
Creating dump of global objects ok
Creating dump of database schemas
ok
Checking for presence of required libraries ok
Checking database user is the install user ok
Checking for prepared transactions ok
Checking for new cluster tablespace directories ok
If pg_upgrade fails after this point, you must re-initdb the
new cluster before continuing.
Performing Upgrade
------------------
Analyzing all rows in the new cluster ok
Freezing all rows in the new cluster ok
Deleting files from new pg_xact ok
Copying old pg_clog to new server ok
Setting oldest XID for new cluster ok
Setting next transaction ID and epoch for new cluster ok
Deleting files from new pg_multixact/offsets ok
Setting oldest multixact ID in new cluster ok
Resetting WAL archives ok
Setting frozenxid and minmxid counters in new cluster ok
Restoring global objects in the new cluster ok
Restoring database schemas in the new cluster
ok
Setting minmxid counter in new cluster ok
Copying user relation files
ok
Setting next OID for new cluster ok
Sync data directory to disk ok
Creating script to delete old cluster ok
Checking for hash indexes ok
Checking for extension updates notice
Your installation contains extensions that should be updated
with the ALTER EXTENSION command. The file
update_extensions.sql
when executed by psql by the database superuser will update
these extensions.
Upgrade Complete
----------------
Optimizer statistics are not transferred by pg_upgrade.
Once you start the new server, consider running:
/usr/pgsql-14/bin/vacuumdb --all --analyze-in-stages
Running this script will delete the old cluster's data files:
./delete_old_cluster.sh
As the output explains, we need to run the generated SQL file to fixup extensions. First we need to start the instance:
systemctl start instantHubPGDB
Then apply the fixes:
/usr/pgsql-14/bin/psql -U instant3dhub -h localhost -p 5433 postgres -f update_extensions.sql
Clean up the pg_ctl workaround:
mv -f /usr/bin/pg_ctl{-orig,}
Next, install the new license server RPM from above.
sudo yum install -y instant3Dhub-licenseServer-CentOS-Linux-7-x64\*.rpm
Now we can start the license server and the upgrade should be complete:
systemctl start instant3DhubLicenseServer
systemctl status instant3DhubLicenseServer
If everything went well, we can now remove the old database data and the old PostgreSQL installation:
# file generated in the folder pg_ugrade was run
./delete_old_cluster.sh
sudo yum remove -y postgresql postgresql-server postgresql-contrib postgresql-libs