Installation Guide

Copyright © 2026 by Symetry, Inc. 14 Pine Street, Ste 6 Morristown, NJ 07960 All Rights Reserved

Introduction

SymetryML is delivered as a Docker image with all dependencies pre-configured, including the application server, Redis, native math libraries, and Spark support. This guide describes how to install, update, and configure SymetryML. For additional information, refer to the following documents:

• SymetryML Technical Requirements
• Installation Guide - Spark
• Installation Guide - GPU
• ML Toolkit

Prerequisites

Before installing SymetryML, ensure the following are in place:

• Docker Engine installed on the host machine.
• SymetryML license file (sym.lic) provided by Symetry.
• (Optional) NVIDIA Container Toolkit if using GPU or Multi-GPU projects — see the GPU Installation Guide.
• (Optional) External Spark 4.1.0 cluster — see the Spark Installation Guide.

Pulling the Docker Image

SymetryML is hosted on Amazon ECR. To pull the image, first authenticate with the registry, then pull.

Step 1 — Authenticate with ECR

SymetryML will provide you with a 12 hours valid token that you can assign to an environment variable (ZTOKEN) and then login to the SymetryML Elastic Container Registry (ECR) with the following command:

docker login -u AWS -p $ZTOKEN 428117700962.dkr.ecr.us-east-1.amazonaws.com

Step 2 — Pull the image

docker pull 428117700962.dkr.ecr.us-east-1.amazonaws.com/sml-server:6.3.0

Running SymetryML

The recommended way to run SymetryML is with Docker Compose. Create a docker-compose.yml file:

services:
  sml-server:
    image: 428117700962.dkr.ecr.us-east-1.amazonaws.com/sml-server:6.3.0
    container_name: sml-server
    ports:
      - "8080:8080"
      - "8443:8443"
    volumes:
      - ./sym.lic:/opt/symetry/sym.lic:ro
    environment:
      - JAVA_OPTS=-server -Xms4096m -Xmx8192m -Dfile.encoding=UTF-8
      - SML_RTLM_DB_REDIS_HOST=localhost
      - SML_RTLM_DB_REDIS_PORT=6379
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped

Start SymetryML:

docker compose up -d

Ports

GPU Support

To enable GPU acceleration, add the NVIDIA runtime and GPU environment variables:

services:
  sml-server:
    image: 428117700962.dkr.ecr.us-east-1.amazonaws.com/sml-server:6.3.0
    container_name: sml-server
    runtime: nvidia
    ports:
      - "8080:8080"
      - "8443:8443"
    volumes:
      - ./sym.lic:/opt/symetry/sym.lic:ro
    environment:
      - JAVA_OPTS=-server -Xms4096m -Xmx8192m -Dfile.encoding=UTF-8
      - NVIDIA_VISIBLE_DEVICES=all
      - LD_LIBRARY_PATH=/usr/local/cuda/lib64:/opt/symetry/nativelib
      - SML_RTLM_DB_REDIS_HOST=localhost
      - SML_RTLM_DB_REDIS_PORT=6379
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped

See the GPU Installation Guide for additional details.

Redis

Redis is bundled inside the Docker image and starts automatically. To use an external Redis instance instead, update the SML_RTLM_DB_REDIS_HOST and SML_RTLM_DB_REDIS_PORT environment variables to point to your external Redis server.

Configuration

Customizing Configuration Files

SymetryML uses two configuration files that control REST API and Web UI behavior:

• symetry-rest.txt — REST API configuration (see SymetryML REST Configuration)
• symetry-web.txt — Web UI configuration (see SymetryML Web Configurations)

To override the default configuration, mount custom files into the container:

volumes:
  - ./sym.lic:/opt/symetry/sym.lic:ro
  - ./symetry-rest.txt:/opt/symetry/symetry-rest.txt:ro
  - ./symetry-web.txt:/opt/symetry/symetry-web.txt:ro

SymetryML Memory Requirements

Please consult the SymetryML Technical Requirements for more information on memory requirements for various project sizes. Note that with SymetryML, project sizes are limited by the number of attributes, not the number of rows.

Memory is configured via the JAVA_OPTS environment variable. Adjust -Xms (minimum heap) and -Xmx (maximum heap) according to your project size:

environment:
  - JAVA_OPTS=-server -Xms4096m -Xmx8192m -Dfile.encoding=UTF-8

SymetryML REST Configuration

SymetryML REST behavior is controlled by the symetry-rest.txt configuration file. The following table provides information about available parameters.

Cross-Origin Resource Sharing (CORS)

The REST API sends no CORS headers by default. To allow browser pages served from another origin to call the API, add -Dsml.rest.cors=true to JAVA_OPTS:

  - JAVA_OPTS=-server -Xms4096m -Xmx8192m -Dfile.encoding=UTF-8 -Dsml.rest.cors=true

When the flag is active, the server logs CORS enabled for REST responses (-Dsml.rest.cors=true) at startup. For the headers this adds and the security implications, see Cross-Origin Resource Sharing (CORS).

SymetryML Web Configurations

Certain SymetryML Web parameters can be configured by editing the symetry-web.txt configuration file.

Updating SymetryML

To update SymetryML, pull the new image version and recreate the container:

docker pull 428117700962.dkr.ecr.us-east-1.amazonaws.com/sml-server:<NEW_VERSION>

Update the image tag in your docker-compose.yml, then restart:

docker compose down
docker compose up -d

Upgrading from 6.x to 7.0

SymetryML 7.0 changes how requests are signed and how credentials are encrypted, and it does not accept 6.x clients or 6.x encrypted data. Plan the upgrade as follows.

1. Snapshot Redis before starting the 7.0 server.
2. Have the stored credentials migrated. Customer credentials and data source definitions are stored encrypted in Redis in the pre-7.0 format and must be re-encrypted in the 7.0 format before the server can use them. Contact SymetryML support to plan this migration before upgrading an existing installation. Until it is done, the 7.0 server answers every request with 503 Service Unavailable. A new installation with an empty Redis needs no migration.
3. Upgrade every client together with the server: pymetry, the SymetryML web UI, the Java client, symetry-mcp and any custom client. A 6.x client is refused with 400 because it sends no sym-version: 7.x header, and its signatures and encrypted bodies are in the old format. See Protocol Version Header.
4. Upgrade every federation member. Every node of a federation or fusion must run 7.0.
5. Review TLS and SFTP trust. Certificates of federation and fusion peers, HTTPS data sources and tls:// NATS servers are now verified, and SFTP host keys must be in known_hosts. Provide a truststore and a known_hosts file where needed (rtlm.option.sml.tls.truststore, rtlm.option.sml.sftp.known_hosts).
6. Re-enable local-file data sources if you use them: they are off by default (rtlm.option.sml.local_ds.enable=1).

Features removed in 7.0 (single sign-on, the Tasks API, third-party XGBoost models, EMR and Dataproc data sources) are listed in the Release Notes.

Troubleshooting

Question: I am getting the following error: java.util.concurrent.ExecutionException: javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

Answer: The remote host (a federation or fusion peer, an HTTPS data source or a tls:// NATS server) presents a certificate that the server does not trust. Since 7.0 certificates are verified by default. If the certificate is signed by a private CA, add that CA to a truststore and set rtlm.option.sml.tls.truststore (and rtlm.option.sml.tls.truststore.password). On a test system only, rtlm.option.sml.tls.trust_all=1 turns verification off. See the SymetryML REST Configuration section for details.