Ontotext Platform CLI

This is the command line tool for managing Ontotext Platform and its components.

Prerequisites

Usage

To list the available commands, use:

docker run -it ontotext/opctl --help

Configuration

The CLI tool depends on supplying a properly configured configuration YAML. Without it, it will not know where to make API requests and what to configure.

First, prepare a configuration file following the instructions in the CLI configuration section. Then mount it inside the Docker container with:

docker run -it -v $(pwd):/etc/opctl/ ontotext/opctl <command>

Where -v $(pwd):/etc/opctl mounts the current working directory inside the container. If the configuration file is elsewhere, provide the correct absolute path.

The next examples will use the current working directory as a source and a configuration file named opctl.yaml.

Wait for Services

You can invoke the CLI and have it wait for remote services to become available before executing the invoked command. This avoids writing scripts to do that before calling the CLI. Example:

docker run -it -v $(pwd):/etc/opctl/ ontotext/opctl <command> --wait --timeout 10000

Note

The timeout flag is in milliseconds.

SOML Provisioning

The CLI tools supports creating or updating existing SOML schemas. To do that, prepare a SOML schema and mount it in the Docker container:

docker run -it -v $(pwd):/etc/opctl/ ontotext/opctl soml upload \
       --config /etc/opctl/opctl.yaml \
       --soml /etc/opctl/schema.yaml

It also supports binding the schema after uploading it with the --bind flag:

docker run -it -v $(pwd):/etc/opctl/ ontotext/opctl soml upload \
       --config /etc/opctl/opctl.yaml \
       --soml /etc/opctl/schema.yaml \
       --bind

Note

Uploading SOML crafts a JWT token with SchemaRBACAdmin role by default. This is the default administrative SOML RBAC role. If you have a different set of RBAC roles, make sure it exists there.

Security Provisioning

The CLI tool supports configuring clean installations of:

FusionAuth

  • API key

  • Tenant and application

  • JWT token and lambda

  • Users and roles

  • Login theme

Kong

  • Services

  • Routes

  • JWT plugin

GraphDB

  • Default repository

  • Users, passwords and roles

  • Enables security

  • Free view for the default repository

This aims to avoid manually configuring multiple services, to ease the initial security configurations, and to have a configured identity provider on deployment install.

To provision the security, use:

docker run -it -v $(pwd):/etc/opctl/ ontotext/opctl provision security \
       --config /etc/opctl/opctl.yaml

Note

The configuration file allows to enable or disable the provisioning separately. For example, to disable Kong’s provisioning, set platform.kong.provision to false.

Warning

Currently, the CLI does not support updating exiting environments.

Warning

Make sure you specify different API keys and user passwords when deploying in different environments. See the security.fusion.apiKey configurations.

Skip Consecutive Provisioning

The CLI supports persistent state that allows already provisioned environments to be omitted on consecutive runs. This helps to avoid damaging environments. The state is saved in a YAML file which is generated using the platform section from default.yaml. Example:

platform:
  service:
    state: NEW
  graphdb:
    state: NEW
  fusion:
    state: NEW
  kong:
    state: NEW

States are changed dynamically during the provision. Possible states are NEW, PROVISIONING, DONE, ERROR.

States DONE and ERROR are skipped on consecutive calls and reported in the execution log. Run the CLI with parameter -r true or --resume to have it enabled.

The state file path is also configurable by providing -p state-file.yaml. If the latter is missing, the default file name is cli-state.yaml. Example:

docker run -it -v $(pwd):/etc/opctl/ ontotext/opctl <command> \
        --config /etc/opctl/opctl.yaml \
        --resume \
        -p state-file.yaml

This will create a -p state-file.yaml file inside the current working directory. The next time this command is invoked, the CLI will use it.

CLI Configuration

The CLI has a default configuration default.yaml with documentations for its fields.

You can override them selectively, e.g., say you wanted to change the service addresses and the system admin username & password, then you can create new YAML file with just the following configurations:

platform:
  service:
    address: http://service:8080

security:
  admin:
    email: system-admin@domain.com
    password: passw0rd

Note

Leaving empty fields will override the default completely. For example, be careful not to leave security: empty otherwise the default values will not be used.

Services

Because the CLI tool runs within a Docker container, it is important to update all service addresses from localhost to either IP addresses or resolvable service names.

For example, if the Semantic Object Service (SOaaS) is resolvable on the semantic-objects address, then its configuration should be:

platform:
  service:
    address: http://semantic-objects:8080

Default Configuration

Download the default opctl.yaml configuration file.