Skip to main content

Match Identity

Match Studio Installation Guides

Installing Match Studio on Linux

Introduction

These instructions are for installing Match Studio on a single machine. Simple instructions for running Match Studio are also included. For more information on running Match Studio, access the Match Studio User Guide via the Help (question mark) icon or by visiting docs.babelstreet.com.

Included files

The following files are included in the Match Studio shipment:

  • match-studio-dockerless-linux-<version>.zip: Linux version of Match Studio

  • rlp-license.xml: License file

  • match-studio-installation-guide-Linux.pdf: This guide

Prerequisites

  • Ubuntu 20.04, RHEL 7/8, CentOS 7, CentOS Stream 8, or Amazon Linux 2

  • At least 16 GB of RAM

  • At least 32 GB of hard disk space

  • Google Chrome version 134.0.6998.88 or higher

Running Match Studio with default Elasticsearch security

Match Studio can now be installed with default Elasticsearch security enabled. This setup automatically creates a user for accessing Elasticsearch and adds a self-signed certificate for SSL. If you choose to enable security during installation, the installer will handle the entire setup for you. If you don't install the security, the local Elasticsearch instance is open to everyone.

When installing the free trial, default security is enabled by default. This is an option when installing the full product.

Set up SSL (optional)

Using SSL ensures that your connection with the server is encrypted. To use SSL, you will need to have the following files ready during installation:

  • PKCS12 certificate (.p12, .pkcs12, .pfx)

  • Client certificate (.pem, .cert, .crt, .cer)

  • Client key (.pem, .key)

Install Match Studio

  1. Extract the contents of match-studio-dockerless-linux-<version>.zip.

  2. Navigate to the match-studio-<version>/ directory.

  3. Run ./install-match-studio.sh. This script installs Match Studio and its dependencies.

  4. When prompted, provide the location of the rlp-license.xml file.

  5. When prompted, choose whether you want to install Match Studio in unlocked mode or locked mode.

    Note

    • Unlocked mode: Enables full access to Match's configurations (including parameters, stop words, and overrides) at the cost of some performance. This mode is useful for testing or in non-production environments.

    • Locked mode: Limits configurability from within Match Studio (configuration access is still available through Match directly). This ensures production environments cannot be modified through Match Studio, and boosts performance.

  6. When prompted, choose whether you want to enable encryption and decryption.

  7. If you selected Yes, choose whether to use an auto-generated password or enter your own password.

    Note

    If you change this password later in the application files, the existing server details will not be valid and need to be re-entered.

  8. When prompted, choose whether you want to enable SSL.

  9. If you selected Yes:

    1. When prompted, enter the complete PKCS12 certificate (.p12) file path.

    2. When prompted, enter the PKCS12 certificate password.

    3. When prompted, enter the complete client certificate (.pem) file path.

    4. When prompted, enter the client key (.pem).

Installing Match Studio without internet access

Match Studio depends on 3 external packages. These packages are downloaded from the internet by the install script (install-match-studio.sh). If the system you are running the install script on does not have internet access, you can download the following packages from the URLs below and place them in the installers directory (match-studio-<version>/installers directory) manually:

  • Elasticsearch for Linux

    • https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-<version>-linux-x86_64.tar.gz

  • Postgresql for Linux

    • http://get.enterprisedb.com/postgresql/postgresql-<version>-linux-x64-binaries.tar.gz

  • Java 21 for Linux

    • For x86_64 system arch:

      https://api.adoptium.net/v3/binary/version/jdk-${adoptium.jdk.version}/linux/x64/jre/hotspot/normal/eclipse

    • For aarch64 system arch:

      https://api.adoptium.net/v3/binary/version/jdk-${adoptium.jdk.version}/linux/aarch64/jre/hotspot/normal/eclipse

Running Match Studio

To start Match Studio, from the match-studio-<version>/ directory run the startup script: ./startup.sh This script starts Match Studio and all its dependencies.

To use Match Studio in a web browser, after starting Match Studio, open Chrome to http://localhost:8090.

Note

If you are running from a server, replace localhost with the IP address of the server.

Note

If you installed Match Studio in locked mode, when you accesses Match Studio for the first time, you will be asked to add a new Elasticsearch server. You will not be able to use Match Studio until you do.

To shut down Match Studio, from the match-studio-<version>/ directory run the shutdown script: ./shutdown.sh.

Running Match Studio on different ports

Should you want Match Studio to run on different ports (for example, if you have port conflicts), complete the following steps:

  1. Shut down the server using the shutdown.sh script.

  2. Open the startup.sh file and locate the following lines:

    export ROS_BACKEND_PORT=8090

  3. Change the ports to your desired ports.

  4. Save and close the file.

  5. Start the server again.

Running Match Studio on a server

To run Match Studio on a server the following changes are needed:

  1. After installation, navigate to the match-studio-<version>/backend directory.

  2. Open the file application.yml in an editor.

  3. Under swagger, update all instances of localhost with the server address. For example:

    swagger:
    host: server.sample.com
    port: 8090/swagger-ui/index.html

  4. Save these changes and proceed with startup.

  5. To access Match Studio, replace localhost with the address of the server in your browser.

In certain cases (for example, configuring HTTPS), you may need to explicitly allow certain origins to access the backend API. To do so, open the file match-studio-<version>/backend/application.yml and add the hosts as follows:

   allowedOrigins:
     hosts:
        - https://allowed-origin-one.com
        - https://allowed-origin-two.com

Updating the license file

If you receive a new license key file, follow these instructions to apply it to an existing Match Studio installation:

  1. Shut down Match Studio.

  2. Back up the existing license key file: match-studio-<version>/bt_roots/licenses/rlp-license.xml.

  3. Copy the new rlp-license.xml file to match-studio-<version>/bt_roots/licenses.

  4. Replace the license key file in the Elasticsearch plugin directory: services/elasticsearch-<version>/plugins/babel-street-match/bt_root/rlp/rlp/licenses.

  5. Restart Match Studio.

Upgrading Match Studio

  1. Shut down Match Studio by navigating to the installation folder and running ./shutdown.sh.

  2. Install the new version of Match Studio in a new directory. (The version number is embedded in the directory name by default.)

  3. When prompted, provide the location of your license key file. If you want to use the same license key file, it is located in the bt_roots/licenses directory of your existing installation.

  4. Start the new version of Match Studio from the new installation directory.

  5. Import data and configurations to your new installation as needed.

You may delete the old installation when you no longer need the data stored in it.

Debugging

To locate additional information about errors, inspect the log file for each Match Studio module. Module logs are located in the following directories under match-studio-<version>. It may be useful to look in each of these logs before contacting us for support:

  • backend/log/backend.log

To delete all data and reset the system:

  1. From the match-studio-<version>/ directory run the shutdown script: ./shutdown.sh.

  2. Delete the directory match-studio-<version>/db_data.

  3. Navigate to the services/ directory and delete the following directories:

    1. elasticsearch-<version>

    2. pgsql

    Important

    DO NOT delete the other files in the services directory. DO NOT delete the other files or directories not specifically listed above. Doing so will require a reinstallation from the original .zip file and license key file.

  4. Follow the basic installation instructions above.

API docs

The Match Studio web application uses a series of RESTful endpoints which are documented at this location:

  • http://localhost:8090/swagger-ui/index.html

Note

If you are running from a server, replace localhost with the IP address of the server.

Installing Match Studio on macOS

Introduction

These instructions are for installing Match Studio on a single machine. Simple instructions for running Match Studio are also included. For more information on running Match Studio, access the Match Studio User Guide via the Help (question mark) icon or by visiting docs.babelstreet.com.

Included files

The following files are included in the Match Studio shipment:

  • match-studio-dockerless-macos-<version>.zip: macOS version of Match Studio

  • rlp-license.xml: License file

  • match-studio-installation-guide-macOS.pdf: This guide

Prerequisites

  • macOS 10.14 Mojave or higher

  • At least 16 GB of RAM

  • At least 32 GB of hard disk space

  • Google Chrome version 134.0.6998.88 or higher (recommended) or Safari version 18.4 (20621.1.15) or higher

Running Match Studio with default Elasticsearch security

Match Studio can now be installed with default Elasticsearch security enabled. This setup automatically creates a user for accessing Elasticsearch and adds a self-signed certificate for SSL. If you choose to enable security during installation, the installer will handle the entire setup for you. If you don't install the security, the local Elasticsearch instance is open to everyone.

When installing the free trial, default security is enabled by default. This is an option when installing the full product.

Set up SSL (optional)

Using SSL ensures that your connection with the server is encrypted. To use SSL, you will need to have the following files ready during installation:

  • PKCS12 certificate (.p12, .pkcs12, .pfx)

  • Client certificate (.pem, .cert, .crt, .cer)

  • Client key (.pem, .key)

Install Match Studio

  1. Extract the contents of match-studio-dockerless-macos-<version>.zip.

  2. Navigate to the match-studio-<version>/ directory.

  3. Run ./install-match-studio.sh. This script installs Match Studio and its dependencies.

  4. When prompted, provide the location of the rlp-license.xml file.

  5. When prompted, choose whether you want to install Match Studio in unlocked mode or locked mode.

    Note

    • Unlocked mode: Enables full access to Match's configurations (including parameters, stop words, and overrides) at the cost of some performance. This mode is useful for testing or in non-production environments.

    • Locked mode: Limits configurability from within Match Studio (configuration access is still available through Match directly). This ensures production environments cannot be modified through Match Studio, and boosts performance.

  6. When prompted, choose whether you want to enable encryption and decryption.

  7. If you selected Yes, choose whether to use an auto-generated password or enter your own password.

    Note

    If you change this password later in the application files, the existing server details will not be valid and need to be re-entered.

  8. When prompted, choose whether you want to enable SSL.

  9. If you selected Yes:

    1. When prompted, enter the complete PKCS12 certificate (.p12) file path.

    2. When prompted, enter the PKCS12 certificate password.

    3. When prompted, enter the complete client certificate (.pem) file path.

    4. When prompted, enter the client key (.pem).

Installing Match Studio without internet access

Match Studio depends on 3 external packages. These packages are downloaded from the internet by the install script (install-match-studio.sh). If the system you are running the install script on does not have internet access, you can download the following packages from the URLs below and place them in the installers directory (match-studio-<version>/installers directory) manually:

  • Elasticsearch for Mac

    • https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-<version>-darwin-x86_64.tar.gz

  • Postgresql for Mac

    • http://get.enterprisedb.com/postgresql/postgresql-<version>-osx-binaries.zip

  • Java 21 for Mac

    • For x86_64 system arch:

      https://api.adoptium.net/v3/binary/version/jdk-${adoptium.jdk.version}/mac/x64/jre/hotspot/normal/eclipse

    • For aarch64 system arch:

      https://api.adoptium.net/v3/binary/version/jdk-${adoptium.jdk.version}/mac/aarch64/jre/hotspot/normal/ecli

Running Match Studio

To start Match Studio, from the match-studio-<version>/ directory run the startup script: ./startup.sh This script starts Match Studio and all its dependencies.

To use Match Studio in a web browser, after starting Match Studio, use a Chrome or Edge web browser to open http://localhost:8090.

Note

If you are running from a server, replace localhost with the IP address of the server.

Note

If you installed Match Studio in locked mode, when you accesses Match Studio for the first time, you will be asked to add a new Elasticsearch server. You will not be able to use Match Studio until you do.

To shut down Match Studio, from the match-studio-<version>/ directory run the shutdown script: ./shutdown.sh.

Running Match Studio on different ports

Should you want Match Studio to run on different ports (for example, if you have port conflicts), complete the following steps:

  1. Shut down the server using the shutdown.sh script.

  2. Open the startup.sh file and locate the following lines:

    export ROS_BACKEND_PORT=8090

  3. Change the ports to your desired ports.

  4. Save and close the file.

  5. Start the server again.

Running Match Studio on a server

To run Match Studio on a server the following changes are needed:

  1. After installation, navigate to the match-studio-<version>/backend directory.

  2. Open the file application.yml in an editor.

  3. Under swagger, update all instances of localhost with the server address. For example:

    swagger:
    host: server.sample.com
    port: 8090/swagger-ui/index.html

  4. Save these changes and proceed with startup.

  5. To access Match Studio, replace localhost with the address of the server in your browser.

In certain cases (for example, configuring HTTPS), you may need to explicitly allow certain origins to access the backend API. To do so, open the file match-studio-<version>/backend/application.yml and add the hosts as follows:

   allowedOrigins:
     hosts:
        - https://allowed-origin-one.com
        - https://allowed-origin-two.com

Updating the license file

If you receive a new license key file, follow these instructions to apply it to an existing Match Studio installation:

  1. Shut down Match Studio.

  2. Back up the existing license key file: match-studio-<version>/bt_roots/licenses/rlp-license.xml.

  3. Copy the new rlp-license.xml file to match-studio-<version>/bt_roots/licenses.

  4. Replace the license key file in the Elasticsearch plugin directory: services/elasticsearch-<version>/plugins/babel-street-match/bt_root/rlp/rlp/licenses.

  5. Restart Match Studio.

Upgrading Match Studio

  1. Shut down Match Studio by navigating to the installation folder and running ./shutdown.sh.

  2. Install the new version of Match Studio in a new directory. (The version number is embedded in the directory name by default.)

  3. When prompted, provide the location of your license key file. If you want to use the same license key file, it is located in the bt_roots/licenses directory of your existing installation.

  4. Start the new version of Match Studio from the new installation directory.

  5. Import data and configurations to your new installation as needed.

You may delete the old installation when you no longer need the data stored in it.

Debugging

To locate additional information about errors, inspect the log file for each Match Studio module. Module logs are located in the following directories under match-studio-<version>. It may be useful to look in each of these logs before contacting us for support:

  • backend/log/backend.log

To delete all data and reset the system:

  1. From the match-studio-<version>/ directory run the shutdown script: ./shutdown.sh.

  2. Delete the directory match-studio-<version>/db_data.

  3. Navigate to the services/ directory and delete the following directories:

    1. elasticsearch-<version>

    2. pgsql

    Important

    DO NOT delete the other files in the services directory. DO NOT delete the other files or directories not specifically listed above. Doing so will require a reinstallation from the original .zip file and license key file.

  4. Follow the basic installation instructions above.

API docs

The Match Studio web application uses a series of RESTful endpoints which are documented at this location:

  • http://localhost:8090/swagger-ui/index.html

Note

If you are running from a server, replace localhost with the IP address of the server.

Installing Match Studio on Windows with MSI

Prerequisites

  • Windows 10 or 11

  • At least 16 GB of RAM

  • At least 32 GB of hard disk space

  • Google Chrome version 134.0.6998.88 or higher

  • Admin permissions

Included files

The following files are included in the Match Studio shipment:

  • match-studio-dockerless-windows-msi-<version>.zip: Windows MSI version of Match Studio

  • rlp-license.xml: License file

  • match-studio-installation-guide-Windows-MSI.pdf: This guide

Running Match Studio with default Elasticsearch security

Match Studio can now be installed with default Elasticsearch security enabled. This setup automatically creates a user for accessing Elasticsearch and adds a self-signed certificate for SSL. If you choose to enable security during installation, the installer will handle the entire setup for you. If you don't install the security, the local Elasticsearch instance is open to everyone.

When installing the free trial, default security is enabled by default. This is an option when installing the full product.

Installing and running Match Studio

  1. Extract the contents of match-studio-dockerless-windows-msi-<version>.zip.

  2. Right click the match-studio Windows installer file and select Install.

  3. When prompted, choose whether you want to install Match Studio in unlocked mode or locked mode.

    Note

    • Unlocked mode: Enables full access to Match's configurations (including parameters, stop words, and overrides) at the cost of some performance. This mode is useful for testing or in non-production environments.

    • Locked mode: Limits configurability from within Match Studio (configuration access is still available through Match directly). This ensures production environments cannot be modified through Match Studio, and boosts performance.

  4. When prompted, choose whether you want to enable encryption and decryption.

  5. If you selected Yes, choose whether to use an auto-generated password or enter your own password.

    Note

    If you change this password later in the application files, the existing server details will not be valid and need to be re-entered.

  6. When prompted, choose whether you want to enable SSL.

  7. If you selected Yes:

    1. When prompted, enter the complete PKCS12 certificate (.p12) file path.

    2. When prompted, enter the PKCS12 certificate password.

    3. When prompted, enter the complete client certificate (.pem) file path.

    4. When prompted, enter the client key (.pem).

  8. When you are done with the setup wizard, two shortcuts will appear on the desktop - Start Match Studio and Stop Match Studio.

  9. Run Start Match Studio as an administrator.

    Note

    If you do not run as an administrator, Match Studio will not work.

  10. When prompted, provide the location of the rlp-license file included with your product shipment.

  11. Navigate to http://localhost:8090 on a browser.

  12. When you want to stop Match Studio, run Stop Match Studio as an administrator.

To uninstall:

  1. Navigate to the Control Panel.

  2. Select Add or Remove Programs.

  3. Uninstall Match Studio.

Upgrading Match Studio

  1. Uninstall Match Studio using the following steps:

    1. Run the Stop Match Studio shortcut.

    2. Launch Add or remove programs from the Control Panel.

    3. Scroll down to Match Studio and select Uninstall.

  2. Delete any files related to match studio under the match-studio-<version> folder and then delete the match-studio-<version> folder.

  3. Install the new version of Match Studio using the steps in Installing and running Match Studio.

Debugging

To locate additional information about errors, inspect the log file for each Match Studio module. Module logs are located in the following directories under match-studio-<version>. It may be useful to look in each of these logs before contacting us for support:

  • backend\log\backend.log

In certain situations, Elasticsearch may have trouble loading our native libraries:

java.lang.UnsatisfiedLinkError: C:\path\to\btnamesutiljni.dll: Can't find dependent libraries

A workaround for this issue is to add the library directory to the Windows PATH as an environment variable:

> C:\...\match-studio-${project.version}\services\elasticsearch-${elasticsearch.version}\
plugins\babel-street-match\bt_root\rlp\bin\amd64-w64-msvc120

For more information on modifying environment variables, see visit the Java help here.

To delete all data and reset the system:

  1. Open a command prompt and navigate to the match-studio-<version> directory.

  2. From the Match Studio directory run the shutdown script: shutdown.bat.

  3. Delete the directory match-studio-<version>\db_data.

  4. Navigate to the services directory and delete the following directories:

    1. elasticsearch-<version>

    2. pgsql

    Important

    DO NOT delete the other files in the services directory. DO NOT delete the other files or directories not specifically listed above. Doing so will require a reinstallation from the original .zip file and license key file.

  5. Follow the basic installation instructions above.

Installing Match Studio with Docker

Introduction

These are instructions for installing Match Studio on a single machine. Simple instructions for running Match Studio are also included. For more information on running Match Studio, access the Match Studio User Guide via the Help (question mark) icon or by visiting docs.babelstreet.com.

Included files

The following files are included in the Match Studio shipment:

  • rlp-license.xml: License file

  • match-studio-installation-guide.pdf: This guide

Prerequisites

  • At least 16 GB of RAM

  • At least 50 GB of hard disk space

  • One of the following supported browsers:

    • Google Chrome version 134.0.6998.88 or higher (RECOMMENDED)

    • Safari version 18.4 (20621.1.15) or higher

Install Match Studio

  1. Extract the contents of match-studio-<version>.zip if you have not done so already.

  2. Copy the included license key file rlp-license.xml into the .bt_roots/licenses directory.

  3. If you want to install Match Studio in locked mode, make the following changes to the ./docker-compose.yml file:

    1. Comment out or delete the entire elastic service.

    2. Comment out or delete the esdata_rni_dir volume.

    3. Comment out or delete the elastic dependency inside the backend service.

    4. Set the RMS_CONFIGURATION_LOCKED environment flag to true on the backend service.

    Note

    • Unlocked mode: Enables full access to Match's configurations (including parameters, stop words, and overrides) at the cost of some performance. This mode is useful for testing or in non-production environments.

    • Locked mode: Limits configurability from within Match Studio (configuration access is still available through Match directly). This ensures production environments cannot be modified through Match Studio, and boosts performance.

  4. (OPTIONAL BUT RECOMMENDED) If you want to enable sensitive data encryption and decryption, change the following configuration in the ./config/application.yml file:

    rms-encryption:
    enabled: false
    password: none

    Note

    If you change the password in the application.yml file, any Elasticsearch servers configured inside Match Studio will no longer be valid and will need to be re-entered.

  5. If you would like to change the default port Match Studio runs on, make the following change to the ./docker-compose.yml file:

    1. Change the left side of the port mapping in the 'backend' service to whichever port you want to expose for the HTML and Backend API. For example, to host the application on port 80, you change 8090:8090 to 80:8090.

  6. In certain cases (configuring HTTPS, for example), you may need to explicitly allow certain origins to access the backend API. To do so, open the file ./config/application.yml and update the allowed hosts, formatting them as a comma-separated list. For example:

    allowedOrigins:
    hosts: https://allowed-origin-one.com,https://allowed-origin-two.com

  7. Match Studio supports SSL for users who want to access it on a secure network. SSL is disabled by default. To enable it, you will need to either get a certificate from a certificate authority, or use a self signed certificate. The certificate should be provided to Match Studio via a PKCS12 keystore.

    1. Add the PKCS12 keystore containing the certificate to the ./keystore folder.

    2. Update the ./docker-compose.yml file to set the following environment variables on the backend service:

      1. RMS_SSL_ENABLED=true

      2. RMS_SSL_KEYSTORE_FILE=<keystore file name>

      3. RMS_SSL_KEYSTORE_PASS=<keystore password>

Running Match Studio

  1. Launch the command-line interface (Terminal or CMD).

  2. Navigate to the unzipped match-studio-<version> directory.

Updating the license file

If you receive a new license file from Babel Street, follow these instructions to apply it to an existing Match Studio installation:

  1. Navigate to the unzipped match-studio-<version> directory.

  2. Shut down Match Studio by running docker-compose down.

  3. Back up the existing license key file: ./bt_roots/licenses/rlp-license.xml.

  4. Copy the new rlp-license.xml file to: ./bt_roots/licenses.

  5. Start up Match Studio by running docker-compose up.

Upgrading Match Studio

  1. Navigate into the unzipped match-studio-<version> directory.

  2. Shut down Match Studio by running docker-compose down.

  3. Install the new version of Match Studio in a new folder using the instructions in the Install Match Studio section.

    Note

    If you want to use the same license key file, it is located in the ./bt_roots/licenses directory of your existing installation.

  4. Start the new version of Match Studio from the new installation directory using the instructions in the Running Match Studio section.

  5. Import data and configurations to your new installation as needed.

  6. You may delete the old installation when you no longer need the data stored in it.

Debugging

Running docker-compose with the --verbose option may help provide information for debugging.

  • Reset system: Match Studio is pre-configured such that data persists between restarts. Ingested documents, configurations and settings remain in the system when you run docker-compose down. To delete all data and return Match Studio to the initial state, run docker-compose down -v.

  • Fix Permission Denied issues under RedHat-based (RHEL, CentOS, Fedora) Linux distributions: If one or more module fails with the AccessDeniedException error, or containers can't write to directories in the package directory (e.g. there are no logfiles in the /logs directory), you may need to fix the SELinux Context. To do this:

    1. Make the ./chcon_vols.sh script executable by running chmod +x ./chcon_vols.sh.

    2. Execute the script: ./chcon_vols.sh.

  • Unhealthy container error (Linux): You may need to increase virtual memory by running:

    sudo sysctl -w vm.max_map_count=262144

API docs

The Match Studio web application uses a series of RESTful endpoints which are documented at this location:

  • http://localhost:8090/swagger-ui/index.html

Note

If you are running from a server, replace localhost with the IP address of the server.

Installing Match Studio with Helm

Introduction

This guide is for the Kubernetes/Helm version of Match Studio. If you are interested in using Match Studio without Docker, please contact Babel Street. To learn more about Babel Street Analytics, please visit our website. For support, please visit babelstreet.my.site.com/support/s/.

Included files

The following files are included in the Match Studio shipment:

  • rlp-license.xml: License file

  • match-studio-installation-guide.pdf: This guide

Prerequisites

  • At least 16 GB of RAM

  • At least 50 GB of hard disk space

  • One of the following supported browsers:

    • Google Chrome version 134.0.6998.88 or higher (RECOMMENDED)

    • Safari version 18.4 (20621.1.15) or higher

Install Match Studio

Note

If you fully uninstall then reinstall your Helm chart, you will need to reconnect any Elasticsearch servers added after installation from inside the Match Studio UI.

  1. Launch a command-line interface.

  2. Extract the contents of ./match-studio-helm-${project.version}.tgz. This will create the ./match-studio/ directory.

    Note

    All configuration changes will be made in the ./match-studio/values.yaml file.

  3. Create a Kubernetes secret called match-studio-license to store the rlp-license.xml file:

    kubectl create secret generic match-studio-license --from-file=<license-file>

  4. (Optional) Create persistent volumes (PVs), if you want to use them. Persistent volumes allow Postgres and Elasticsearch data to persist between restarts.

    Note

    PV names can be customized by changing storage.elasticsearch.pvName and storage.postgres.pvName inside the values.yaml file. The default values for these are match-studio-elasticsearch-pv and match-studio-postgres-pv.

    For more information on the various types of persistent volumes and how to create them, see the Kubernetes online documentation.

  5. (Optional) If you want to use Match Studio in locked mode, change configurationLocked to true inside values.yaml.

    Note

    • Unlocked mode: Enables full access to Match's configurations (including parameters, stop words, and overrides) at the cost of some performance. This mode is useful for testing or in non-production environments.

    • Locked mode: Limits configurability from within Match Studio (configuration access is still available through Match directly). This ensures production environments cannot be modified through Match Studio, and boosts performance.

  6. (Optional) If you would like to provide a custom password for the internal Postgres account, create a Kubernetes secret called match-studio-postgres-creds with a password key. For example:

    kubectl create secret generic match-studio-postgres-creds --from-literal=password=mysecretpassword

  7. (Optional) If you want to change the default port Match Studio runs on, update the backend.port value inside the values.yaml file. The port must be in the range of 30000-32767.

  8. In certain cases, such as configuring HTTPS, you may need to explicitly allow certain origins to access the backend API. To do so, update the backend.allowedOrigins value inside the values.yaml file with a comma-separated list of origins. For example:

    backend: 
    allowedOrigins: https://allowed-origin-one.com:8090,https://allowed-origin-two.com:1234

  9. (Optional) Match Studio supports SSL so that users can access match studio on a secure network. SSL is disabled by default. To enable it:

    1. Create a Kubernetes secret called 'match-studio-keystore' to store the keystore and password. (You will need to get a certificate from a certificate authority, or use a self signed certificate. The certificate should be provided to Match Studio via a PKCS12 keystore.)

      kubectl create secret generic match-studio-keystore \
   --from-literal=password=changeit \
   --from-file=keystore=/<PATH-TO-KEYSTORE>/keystore.pkcs12

    2. In the values.yaml file, set backend.sslEnabled to true.

Running Match Studio

  1. Launch the command-line interface (Terminal or CMD).

  2. Navigate to the unzipped match-studio-<version> directory.

Upgrading Match Studio

  1. Shut down Match Studio.

  2. Install the new version of Match Studio in a new folder by following the instructions in the Install Match Studio section.

  3. Start the new version of Match Studio from the new installation directory.

  4. Import data and configurations to your new installation as needed.

  5. Delete the old installation when you no longer need the data stored in it.

Troubleshooting

  • kubectl commands: You can inspect the Kubernetes pod using kubectl commands. For example:

    kubectl get pods
kubectl describe pod <pod-name>
kubectl logs <pod-name>

  • Port forwarding: If Match Studio is not accessible at the expected port (default 30080) after a couple minutes, you may need to set up a port-forward in your Kubernetes cluster. While this step depends on your specific setup, the command will look similar to this:

    kubectl port-forward --address 0.0.0.0 pod/<pod-name> 30080:8090

    Note

    For more information on this command, see the Kubernetes online documentation.

  • Reset the system:

    1. Uninstall Match Studio: helm uninstall match-studio

    2. Clear and/or recreate any persistent volumes. This process will vary depending on the type of persistent volume.

    3. Reinstall Match Studio: helm install match-studio ./match-studio

See also: