Skip to main content

Quick start

This guide provides simple instructions to get a single host instance of KeySquare running quickly on Linux.

For more detailed deployment instructions, please see Deployment Guide.

Installing​

The KeySquare platform can be installed in the following forms:

  • Container platform using Docker.
  • Bare-metal platform on Linux.
info

Please contact Sales for installation file(s) and a licence key.

1. Extract Installation Files​

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​

minimum requirements

Must have tar, openssl, docker-composer 2.24.0+, and docker 25.0+ installed

Run the setup.sh script from the keysquare-docker-(version) directory that was extracted:

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

Example Output​

Setup output
./setup.sh

██╗  ██╗███████╗██╗   ██╗███████╗ ██████╗ ██╗   ██╗ █████╗ ██████╗ ███████╗
██║ ██╔╝██╔════╝╚██╗ ██╔╝██╔════╝██╔═══██╗██║   ██║██╔══██╗██╔══██╗██╔════╝
█████╔╝ █████╗   ╚████╔╝ ███████╗██║   ██║██║   ██║███████║██████╔╝█████╗
██╔═██╗ ██╔══╝    ╚██╔╝  ╚════██║██║▄▄ ██║██║   ██║██╔══██║██╔══██╗██╔══╝
██║  ██╗███████╗   ██║   ███████║╚██████╔╝╚██████╔╝██║  ██║██║  ██║███████╗
╚═╝  ╚═╝╚══════╝   ╚═╝   ╚══════╝ ╚══▀▀═╝  ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝

=== KeySquare Docker Platform Setup ===
Version: 1.1.3

=== SETUP PROFILE ===

Base directory
KeySquare home base: apps, runtime files, config, logs, and working data live here.

Base directory [~/keysquare]:
-> ~/keysquare

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

Host name
Lower-case KeySquare identity for this server, used for host-specific config and process definitions.

Host name [kstest01]:
-> kstest01

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

Host instance
Numeric instance id for process names on this host. Use 1 unless this host runs multiple platform instances.

Host instance [1]:
-> 1

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

Created setup profile: $HOME/.config/keysquare/keysquare.properties

=== KEYSQUARE APP SETUP ===

[done] Loading available Docker images (5s)
Docker Compose package:
PACKAGE                      INSTALLED        BUNDLE
---------------------------- ---------------- ----------------
docker                       not installed    1.1.3

Docker image archive:
IMAGE                            INSTALLED        AVAILABLE VERSION STATUS
-------------------------------- ---------------- ---------------- --------------
key-access                       not loaded       1.1.3            load (yes)
key-ui                           not loaded       1.1.3            load (yes)
keysquare-proxy                  not loaded       1.1.3            load (yes)
ks-quest                         not loaded       1.1.3            load (yes)
sequencer                        not loaded       1.1.3            load (yes)
relay-live                       not loaded       1.1.3            load (yes)
relay-cache                      not loaded       1.1.3            load (yes)
web-data-server                  not loaded       1.1.3            load (yes)
ks-ingress-controller            not loaded       1.1.3            load (yes)
ks-grafana                       not loaded       1.1.3            load (yes)
aeron-media-driver               not loaded       1.1.3            load (yes)
monitor                          not loaded       1.1.3            load (yes)

Load all available Docker images [Y/n]:
Preparing Docker package files in $HOME/keysquare...
[done] Copying Docker image archive (0s)
Installed bin/docker-env.sh
Installed bin/ks-platform.sh
Preparing Docker Compose app in $HOME/keysquare/apps/docker/1.1.3...
Installed apps/docker/1.1.3/docker-compose-platform.yaml
Linked apps/docker/latest -> 1.1.3
[done] Loading Docker images (8s)
Loaded image: gitea.keysquare.trading/keysquare/ks-grafana:1.1.3
Loaded image: gitea.keysquare.trading/keysquare/ks-quest:1.1.3
Loaded image: gitea.keysquare.trading/keysquare/aeron-media-driver:1.1.3
Loaded image: gitea.keysquare.trading/keysquare/sequencer:1.1.3
Loaded image: gitea.keysquare.trading/keysquare/relay-live:1.1.3
Loaded image: gitea.keysquare.trading/keysquare/relay-cache:1.1.3
Loaded image: gitea.keysquare.trading/keysquare/monitor:1.1.3
Loaded image: gitea.keysquare.trading/keysquare/key-access:1.1.3
Loaded image: gitea.keysquare.trading/keysquare/key-ui:1.1.3
Loaded image: gitea.keysquare.trading/keysquare/web-data-server:1.1.3
Loaded image: gitea.keysquare.trading/keysquare/keysquare-proxy:1.1.3
Loaded image: gitea.keysquare.trading/keysquare/ks-ingress-controller:1.1.3
Removed staged Docker image archive: $HOME/keysquare/keysquare.tar.gz

=== CONFIG + FILE STRUCTURE SETUP ===

Added conf/db.properties
Added conf/logback-app.xml
Added conf/net.properties
Added conf/secrets.properties
Added certs/README.md
Licence key: test-licence
Installed licence file: $HOME/keysquare/conf/licence.key
Created platform host config: $HOME/keysquare/conf/kstest01.properties

=== 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.

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


=== 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.

=== Docker Setup Complete ===
Base:                 $HOME/keysquare
Docker app:           $HOME/keysquare/apps/docker/latest
Config:               $HOME/keysquare/conf
Platform secrets:     $HOME/keysquare/conf/secrets.properties
Licence file:         $HOME/keysquare/conf/licence.key
Setup profile:        $HOME/.config/keysquare/keysquare.properties
Platform host config: $HOME/keysquare/conf/kstest01.properties
Logs:                 $HOME/keysquare/var/logs

Next steps:
1. Review config under $HOME/keysquare/conf
2. Start platform: $HOME/keysquare/bin/ks-platform.sh start

Would you like to launch the platform [Y/n]:

HOSTNAME: [kstest01]
KS_HOSTNAME: [kstest01]
KS_HOST_INSTANCE: [1]
USER_UID: [314200022]
USER_GID: [976]
REGISTRY: [gitea.keysquare.trading/keysquare]
KS_HOME: [$HOME/keysquare]
DOCKER_APP_DIR: [$HOME/keysquare/apps/docker/latest]
DOCKER_PROJECT_DIR: [$HOME/keysquare]
DOCKER_ENV_SOURCE_FILE: [$HOME/keysquare/apps/docker/latest/docker-compose-platform.yaml]
File exists: $HOME/keysquare/conf/net.properties
File exists: $HOME/keysquare/conf/secrets.properties
File exists: $HOME/keysquare/conf/db.properties
File exists: $HOME/keysquare/conf/kstest01.properties
Executing: docker compose --project-directory $HOME/keysquare --profile all --env-file $HOME/keysquare/conf/net.properties --env-file $HOME/keysquare/conf/secrets.properties --env-file $HOME/keysquare/conf/db.properties --env-file $HOME/keysquare/conf/kstest01.properties -f $HOME/keysquare/apps/docker/latest/docker-compose-platform.yaml -p keysquare up -d
[+] up 12/12
✔ Container aeron-media-driver    Started                                                             0.6s
✔ Container ks-quest              Healthy                                                            28.1s
✔ Container ks-ingress-controller Started                                                             0.6s
✔ Container ks-grafana            Started                                                            28.0s
✔ Container key-access            Started                                                            28.0s
✔ Container sequencer             Started                                                            28.1s
✔ Container relay-live            Healthy                                                            40.1s
✔ Container relay-cache           Healthy                                                            40.1s
✔ Container monitor               Healthy                                                            42.6s
✔ Container keysquare-proxy       Started                                                            42.7s
✔ Container web-data-server       Healthy                                                            49.2s
✔ Container key-ui                Started                                                            49.2s
[done] Waiting for web entrypoint at http://kstest01:6500/ (4s)

============================================================
You're up and running here: http://kstest01:6500/

Sign in as admin using the Admin UI password configured during setup.
============================================================

Running Your Platform​

From the 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:

./ks-platform.sh status
tip

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

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

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 config host-file

remove stops and removes containers without removing their volumes. config host-file prints the resolved Compose configuration.

Next Steps​

Configuration can be found in the keysquare/conf directory.

See the Deployment Guide and Configurations for more information.

Ready to build your first application?

Learn how to do so in the language of your choice: