matrix/cygnus-installer/README.md

Technobee Service Installer

One Swing-based Java installer supports Matrix and Cygnus through an external INI product profile. It never connects to PostgreSQL or Redis. The selected product cloud service validates the activation key and registers the installation.

Build and run

mvn -pl cygnus-installer -am package
TECHNOBEE_INSTALLER_CONFIG=cygnus-installer/config/matrix-installer.ini \
java -jar cygnus-installer/target/technobee-service-installer-1.0.0-SNAPSHOT.jar

Use config/cygnus-installer.ini for Cygnus. Before production use, set the cloud URL and the cloud assertion-encryption public-key path in the selected INI. Both profiles use these cloud endpoints by default:

• POST /api/v1/installations/activation/validate
• POST /api/v1/installations/register

The desktop wizard is the default. It checks Docker, collects activation and installation details, asks for the Docker registry, image, username, and password, lets the user choose an output directory, and reports installation progress. It authenticates with docker login --password-stdin; the registry password is never written into generated files or command arguments. For servers without a desktop or for automation, append --cli to retain the interactive terminal workflow:

TECHNOBEE_INSTALLER_CONFIG=cygnus-installer/config/matrix-installer.ini \
java -jar cygnus-installer/target/technobee-service-installer-1.0.0-SNAPSHOT.jar --cli

Configuration

[installer]
product=matrix
cloud_service_url=https://cloud.example.com
installer_api_base_path=/api/v1/installations
environment=production
output_directory=./matrix-installation

[profile.matrix]
display_name=Matrix
service_name=matrix-onprem
image_environment_variable=MATRIX_IMAGE
configuration_root=matrix
configuration_file_name=installation.yml
installation_config_environment_variable=MATRIX_INSTALLATION_CONFIG
container_configuration_path=/opt/matrix/config/installation.yml
port_mapping=8080:8080
token_path=/oauth2/token
assertion_encryption_public_key=/secure/cloud-assertion-public.pem
optional_fields=

The installer validates the product, URL, API path, environment, profile values, and public-key file before asking installation questions.

Generated output

.env
compose.yml
config/
  installation.yml
  machine-assertion.jwt
  keys/
    client-signing-private.pem
    client-signing-public.pem

The installer asks for the product Docker image, validates it, and stores it under the profile's image variable in .env. Docker Compose loads this file automatically, so no separate export MATRIX_IMAGE or export CYGNUS_IMAGE step is required. Docker stores successful login state using its configured credential store; the installer does not persist the registry password.

The RSA-3072 pair is generated locally. Only the public key is sent during registration. The private key and encrypted machine assertion remain on premises and receive owner-only permissions on POSIX systems. The activation key is never written to disk.

scripts/setup-local-communication.sh remains a development/provisioning utility; it is not used by this installer.