Skip to main content

Deployment Guide

This guide covers the two supported deployment styles:

  1. Container platform - Docker images loaded from a platform tarball and run with Docker Compose.
  2. Bare-metal platform - split release packages managed by Platform Manager.

For a shorter single-host walkthrough, see Quick Start.

Minimum Requirements​

AreaRequirement
Processor32 cores
Disk100 GB free space
RAM128 GB
Shared MemoryWritable /dev/shm
NetworkMulticast between servers
DNSIngress hostname resolves from clients
FirewallIngress ports allowed
ShellBash access
JavaJava 21+
Node.jsNode.js 20.9.0+
LicenceKeySquare licence key available
Docker25.0+
Docker Compose2.24.0+
tarNeeded for retrieving package contents
OpenSSLNeeded for Platform Secrets

Installing the Platform​

1. Extract Installation Files​

Docker access

The installing user must be able to run Docker and Docker Compose:

docker --version
docker compose version

Extract the archive file. This creates a keysquare-docker-(version)/ directory in which setup files will be placed.

tar xvzf keysquare-docker-(version).tar.gz

2. Run Setup​

Run setup from the extracted keysquare-docker-(version)/ directory.

cd keysquare-docker-(version)
./setup.sh

2.1 Configuring Setup Profile​

During setup, you will be prompted for three core values used to run the KeySquare platform:

  1. KS_HOME: The directory where KeySquare is installed. This is used to locate platform files, configuration, and executables.
  2. KS_HOSTNAME: The hostname used to resolve host-specific configuration from KS_HOME/conf/<host-name>.properties.
  3. KS_HOST_INSTANCE: The instance identifier for applications running on this host. This is mainly used in multi-host deployments where the same component runs on multiple hosts, such as monitor-1 with KS_HOST_INSTANCE=1 and monitor-2 with KS_HOST_INSTANCE=2.

Once prompted these values will be stored at $HOME/.config/keysquare/keysquare.properties. These can be updated manually at a later date.

2.2 Installing/Updating Apps​

For container deployments, the Docker package is installed as one platform a versioned docker bundle. The setup script installs the Compose files under apps/docker/(version), updates apps/docker/latest, and loads the packaged Docker images fromkeysquare.tar.gz from the setup directory.

keysquare/
├── apps/
│   └── docker/
│       ├── (version)/
│       │   └── docker-compose-platform.yaml
│       └── latest -> (version)
└── bin/
    ├── docker-env.sh
    └── ks-platform.sh

The Compose package is installed or updated as one bundle. Image loading defaults to all available images; declining that prompt offers an advanced path for choosing images individually. The Compose bundle defines the services included in the release even when an image is not loaded locally.

For an update, extract the new Docker release and run setup again:

tar xvzf keysquare-docker-(version).tar.gz
cd keysquare-docker-(version)
./setup.sh

During an update, setup shows the installed and available Docker package and image versions before prompting. It prompts separately for the Docker Compose package update and the packaged Docker image load:

Existing KeySquare installation found: $HOME/keysquare
  Continue to refresh package-managed platform files and review package updates.
  Stop to leave this installation untouched before any package files are copied.

Continue with existing KeySquare installation at $HOME/keysquare [Y/n]:

=== KEYSQUARE APP SETUP ===

  [done] Loading available Docker images (5s)
Docker Compose package:
  PACKAGE                      INSTALLED        BUNDLE
  ---------------------------- ---------------- ----------------
  docker                       1.1.0            1.1.1

Docker image archive:
  IMAGE                            INSTALLED        AVAILABLE VERSION STATUS
  -------------------------------- ---------------- ---------------- --------------
  key-ui                           1.1.0            1.1.1            update (yes)
  web-data-server                  not loaded       1.1.1            load (yes)

Update Docker Compose package from 1.1.0 to 1.1.1 [Y/n]:
Load all available Docker images [Y/n]:

If the Docker platform is running, setup asks to stop it before copying Compose files or loading images. It streams the Docker Compose stop output, performs the update, and offers to start the platform again. Set KS_SETUP_RESTART_PLATFORM=yes for the same stop-and-restart flow in non-interactive setup.

2.3 Configuring Platform Network Addresses​

Every install/update presents the current sequencer input, sequencer output, and key access discovery addresses. Press Enter to keep an address, or enter a replacement.

warning

The final octet of the IPv4 addresses provided as input must be an odd number. If not you will be warned and re-prompted.

Example:

Sequencer input address [224.0.0.1]: 224.0.0.2
  Warning: Enter an IPv4 address with an odd-numbered final octet.
=== PLATFORM NETWORK ADDRESSES ===

Review the shared addresses used by platform services. Press Enter to keep each current value.
Important: Each IP address must end with an odd-numbered final octet.

Sequencer input address
  IP address applications use to send messages for sequencing.

Sequencer input address [224.0.0.1]:
  -> 224.0.0.1
  Kept sequencer input address.

----------------------------------------

Sequencer output address
  IP address applications use to receive sequenced messages.

Sequencer output address [224.0.0.3]:
  -> 224.0.0.3
  Kept sequencer output address.

----------------------------------------

Key access discovery address
  IP address key access servers use to discover cluster peers.

Key access discovery address [224.0.0.5]:
  -> 224.0.0.5
  Kept key access discovery address.

----------------------------------------

2.4 Configuring Initial Platform Secrets​

On a fresh install, setup requires an Admin UI password, this value has no default and is mandatory. The setup asks for the password twice, if entered incorrectly or blank you'll be re-prompt. Automation can provide it through KS_WEB_DATA_SERVER_ADMIN_PASSWORD. Setup then uses OpenSSL to generate every other platform secret automatically and writes all values to KS_HOME/conf/secrets.properties.

=== OVERRIDE DEFAULT PLATFORM SECRETS ===

Fresh KeySquare install detected. An Admin UI password is required.
All other platform secrets will be generated automatically.

Admin UI password
  Password for signing in to the KeySquare Admin UI.

Enter Admin UI password:
Re-enter Admin UI password:
  Admin UI password saved.

----------------------------------------

  Generating key access service key... done
  Generating key access cluster token... done
  Generating Grafana admin password... done
  Generating QuestDB HTTP password... done
  Generating QuestDB Postgres password... done

Important: If another platform will use this key access cluster,
  KS_KEY_ACCESS_CLUSTER_TOKEN must have the same value on every platform.

Platform secrets are stored in:
  $HOME/keysquare/conf/secrets.properties
Edit this file to update them later.

The generated file contains these shared properties:

KS_KEY_ACCESS_SERVICE_KEY=<shared-service-key>
KS_KEY_ACCESS_CLUSTER_TOKEN=<cluster-token>
KS_WEB_DATA_SERVER_ADMIN_PASSWORD=<admin-password>
KS_GRAFANA_ADMIN_PASSWORD=<grafana-password>
KS_QUESTDB_HTTP_PASSWORD=<questdb-http-password>
KS_QUESTDB_PG_PASSWORD=<questdb-postgres-password>

Existing installations keep their current secrets; setup does not regenerate them during a package update.

warning

Platforms that share a key access cluster must use the same KS_KEY_ACCESS_CLUSTER_TOKEN.

3. Review the Install​

Anatomy of the Install KS_HOME Docker Compose Directory Layout
   keysquare/
   ├── apps/
   │   └── docker/
   │       └── latest -> (version) # Symlink to the active installed version
   |           └── docker-compose-platform.yaml # Docker compose file for the KeySquare platform
   ├── bin/ # Used to hold common scripts
   |   ├── docker-env.sh # Used by compose for paths, env files, registry, version, and project name.
   |   └── ks-platform.sh # Main script for stopping/starting the platform
   ├── conf/ # Configurations
   │   ├── net.properties
   |   ├── db.properties
   |   ├── .
   |   ├── .
   |   ├── .
   │   └── secrets.properties
   └── var/
       └── logs/ # GC logs; Docker app logs go to stdout/stderr.
Anatomy of the Container Directory Layout, Monitor for example
   keysquare/
   ├── apps/
   │   └── monitor/
   │       └── latest -> (version)
   |           ├── conf/
   |           |   ├── logback-app.xml
   |           |   └── monitor.proc-def.yaml.template # Template of a process definition for the application
   |           └── monitor.jar 
   ├── bin/ # Used to hold common scripts
   |   ├── entrypoint.sh
   |   ├── ks-env.sh
   |   └── mainclass.sh
   ├── conf/ # Configurations
   │   ├── net.properties
   |   ├── db.properties
   |   ├── .
   |   ├── .
   |   ├── .
   │   ├── secrets.properties
   |   └── process/
   └── var/
       ├── logs/ # GC logs; Docker app logs go to stdout/stderr.
       ├── data/ # Persistent runtime data written by platform components
       ├── health/ # Health/readiness marker files used by monitoring and process checks
       └── profiles/ # Captured profiling artefacts such as JFR or async-profiler output

Running the Platform​

From the installed $HOME/keysquare/bin directory, use ks-platform.sh.

Start the platform:

./ks-platform.sh start

Stop the platform:

./ks-platform.sh stop

Restart the platform:

./ks-platform.sh restart

Get Status of the platform:

Used to verify the platform.

./ks-platform.sh status

Without a comma-separated app list, these commands act on the whole platform.

tip

Pass Compose service names as one comma-separated argument to manage only those services:

./ks-platform.sh start sequencer,monitor
./ks-platform.sh stop sequencer,monitor
./ks-platform.sh restart sequencer,monitor
./ks-platform.sh status sequencer,monitor

Selected stop leaves containers in place, while remove stops and removes containers without removing their volumes:

./ks-platform.sh remove sequencer,monitor
./ks-platform.sh remove

For a host-specific Compose file, put host-file before the optional service list:

./ks-platform.sh start host-file sequencer,monitor
./ks-platform.sh stop host-file
./ks-platform.sh config host-file

config host-file prints the resolved Compose configuration. The secondary mode remains available for relay-only hosts.

Configuring the Platform​

Configuration And Secrets​

Restart after config changes

Configuration is read on startup. Restart the platform after changing conf files.

Configuration lives under $HOME/keysquare/conf. TLS certificates and keys live in the sibling $HOME/keysquare/certs directory. One rule keeps the install tidy: package files live under apps, while deployment choices and local overrides live under conf.

FileUse
net.propertiesIngress hostname, exposed ports, and service URLs
db.propertiesQuestDB or Oracle connection settings
secrets.propertiesShared secrets and passwords
<component>.secrets.propertiesComponent-specific secret files exist for advanced layouts, but most deployments should not need them.
platform-manager.propertiesBare-metal Platform Manager API, auth, audit, diagnostics, JFR, and profiling
platform-manager-tui.propertiesTUI connection, token-file, refresh, timeout, and TLS settings
<lowercase-host-name>.propertiesHost identity, host-specific overrides, and bare-metal process sources
override.propertiesFinal local override file for advanced deployment layouts
../certs/TLS certificates and keys for HTTPS where enabled; installed at $HOME/keysquare/certs

Put server-specific values in the host file. Keep package-owned files under $HOME/keysquare/apps read-only in practice; they belong to installed versions.

Updating/Adjusting Process Definitions​

Process definitions are local operational configuration. Package updates install new app versions and new templates, but existing host-owned process definition files are kept so local JVM args, dependencies, autostart choices, and health checks are not silently replaced.

Container images carry app-owned process definition templates, and the entrypoint renders a writable process definition under conf/process the first time a service starts. If conf/process/<app-name>.proc-def.yaml already exists, the container uses that file instead of re-rendering the image template.

To adjust a container process definition, edit the host-mounted file and restart the affected service or the platform:

cd $HOME/keysquare
./bin/ks-platform.sh stop
vi conf/process/<app-name>.proc-def.yaml
./bin/ks-platform.sh start

Container process definitions are mainly used by the entrypoint for JVM options such as jvmArgs. Docker Compose controls the container lifecycle, mounts, networks, ports, and image tags.

To accept the current image's packaged template again, stop the platform, move the local process definition out of the way, and start the platform so the entrypoint can render a fresh file:

cd $HOME/keysquare
./bin/ks-platform.sh stop
mv conf/process/<app-name>.proc-def.yaml conf/process/<app-name>.proc-def.yaml.bak
./bin/ks-platform.sh start

Verify the Platform​

Open Key UI from a browser:

http://<server>:6500

Then check platform status from $HOME/keysquare/bin:

./ks-platform.sh status

You should be presented with Healthy which means that the Key UI loads, the required services are running, no required process is in a failed/restarting state, and no errors are in logs.

For container installs, check Compose state and recent logs from $HOME/keysquare:

docker compose --project-directory . -f apps/docker/latest/docker-compose-platform.yaml -p keysquare ps
docker compose --project-directory . -f apps/docker/latest/docker-compose-platform.yaml -p keysquare logs --tail=100

Updating the Platform​

Use setup for package updates.

Update Packages​

Extract the new Docker release and run setup:

tar xvzf keysquare-docker-(version).tar.gz
cd keysquare-docker-(version)
./setup.sh

Roll Back​

To roll back one already installed component, stop the platform, repoint latest, and start again:

cd $HOME/keysquare/bin
./ks-platform.sh stop
ln -sfn (version) $HOME/keysquare/apps/docker/latest
./ks-platform.sh start

Explore the Platform​

Suggested first tour

Create a workspace, open Viewer, confirm schemas are visible, register a demo application, then generate its API key. That path proves Key UI, Web Data Server, KeyAccess, ingress, and database wiring are all talking to each other.

Once Key UI loads, start with workflows rather than package names. This route gives users, developers, and operators a quick feel for what the platform can do.

AreaWhat to tryMore detail
WorkspaceBuild a saved layout from live views and service modules, then share it with users or groups.Workspaces
Data toolsUse Viewer for schemas and live data, RPC for service workflows, View Builder for reusable views, and View Defs/Table Defs for saved definitions.Data Viewer
Admin toolsUse App Monitor for health, Permissions for users/apps/API keys/entitlements, and Modules to expose Key UI features by role.Monitoring, Application Management, Configurations
AuthenticationConfigure how users sign in before Key UI roles and data permissions apply.Authentication
Service modulesEnable workflows for instruments, business dates, prices, quotes, curves, and bond analytics.Static Data, Price Engine, Quote Engine, Analytics Engine
ObservabilityUse the bare-metal TUI for process operations and Grafana for platform dashboards.Monitoring
Client toolsBuild client apps with Java or Python, or connect business users through the Excel add-in.Java, Python, Excel

Networking​

These defaults can be changed in net.properties.

Multicast​

The platform requires 5 administratively scoped multicast addresses, comprised of three blocks:

BlockUseInfo
1Sequencer-InA pair of consecutive addresses, with the first one ending with an odd number, e.g. 239.192.0.1 and 239.192.0.2
2Sequencer-OutA pair of consecutive addresses, with the first one ending with an odd number, e.g. 239.192.0.3 and 239.192.0.4
3Key AccessA single address, e.g. 239.192.0.5

In the example above, a five-address block between 239.192.0.1 and 239.192.0.5 inclusive would be used.

Default Routes​

RouteApplicationURL
*Key UIhttp://<server>:6500
/api/webWeb Data Serverhttp://<server>:6500/api/web
/api/key-accessKeyAccesshttp://<server>:6500/api/key-access
/api/proxyKeySquare Proxyhttp://<server>:6500/api/proxy
/app/grafanaGrafanahttp://<server>:6500/app/grafana
/app/questdbQuestDBhttp://<server>:6500/app/questdb

Direct ports are usually for troubleshooting:

ApplicationPropertyDefault
Ingress HTTPKS_INGRESS_HTTP_PORT6500
Ingress HTTPSKS_INGRESS_HTTPS_PORT6501
Platform Manager APIKS_PLATFORM_MANAGER_PORT18443
KeySquare Proxy gRPCKS_KEY_SQUARE_PROXY_GRPC_PORT6700
GrafanaKS_GRAFANA_HTTP_PORT5500
QuestDB HTTP / PostgreSQLKS_QUESTDB_HTTP_PORT, KS_QUESTDB_PG_PORT5510, 5512

Start Building​

Ready to build your first application?