Install

Prerequisites

RemotiveTopology runs the topology with the help of docker containers that interact with each other. Thus, you need Docker. RemotiveTopology also supports Podman as an alternative, simply replace docker with podman in all instructions.

To develop behavioral models for RemotiveTopology, you need Python 3.9 or later.

Subscriptions are handled with Remotive CLI. You need version 0.3.0 or later.

RemotiveTopology login

To use RemotiveTopology, your organization must have an active subscription. If your organization is already a customer of RemotiveLabs, a subscription is likely already in place. Access to the service requires logging in with your organizational credentials to verify the subscription.

For new users who wish to evaluate RemotiveTopology, it’s possible to create a trial subscription. This trial provides temporary access to explore the features and capabilities of the service. Once the trial period expires, you need to contact RemotiveLabs to purchase a full subscription and continue using RemotiveTopology.

To login and optionally create a trial subscription.

1. If you're not part of an existing organization, create an account at RemotiveCloud. This automatically creates an organization.
2. Install the RemotiveCLI.
3. Use RemotiveCLI to log in to your account, then create your trial license.

      remotive cloud auth login
4. Create a trial license if necessary.

      remotive topology start-trial

For pricing information and to discuss your specific requirements, please reach out RemotiveLabs sales.

Installation

RemotiveTopology is currently installed using Docker (or Podman). To install or upgrade to latest version:

docker pull remotivelabs/remotive-topology:latest

Then follow these instructions depending on platform:

MacOS

Add the following alias in for example ~/.zshrc:

alias remotive-topology='docker run \
  --rm \
  -v $HOME/.config/remotive/:/root/.config/remotive \
  -v $(pwd):$(pwd) \
  -w $(pwd) \
  -e REMOTIVE_CLOUD_ORGANIZATION=$REMOTIVE_CLOUD_ORGANIZATION \
  -e REMOTIVE_CLOUD_AUTH_TOKEN=$REMOTIVE_CLOUD_AUTH_TOKEN \
  -it remotivelabs/remotive-topology:latest'

Restart your terminal.

Linux

1. Add the following alias in for example ~/.bashrc:

alias remotive-topology='docker run \
  -u $(id -u):$(id -g) \
  --rm \
  -v $HOME/.config/remotive/:/.config/remotive \
  -v $(pwd):$(pwd) \
  -w $(pwd) \
  -e REMOTIVE_CLOUD_ORGANIZATION=$REMOTIVE_CLOUD_ORGANIZATION \
  -e REMOTIVE_CLOUD_AUTH_TOKEN=$REMOTIVE_CLOUD_AUTH_TOKEN \
  -e REMOTIVE_CONFIG_DIR=/.config/remotive \
  -it remotivelabs/remotive-topology:latest'

Restart your terminal.

2. Install can-utils

sudo apt update
sudo apt install can-utils

3. Install DockerCAN

Download and install the latest version of DockerCAN from https://releases.remotivelabs.com/#docker_can/

mkdir dockercan
tar xvf dockercan-VERSION.tar.gz -C dockercan
cd dockercan
make
cd ..
rm -rf dockercan

Windows

In PowerShell open your profile:

notepad $PROFILE

Add the following code at the bottom:

function remotive-topology {
   $configDir = "${HOME}\.config\remotive"

   $dockerParams = @(
       "run",
       "--rm",
       "-v", "${PWD}:/data",
       "-v", "${configDir}:/root/.config/remotive/",
       "-w", "/data",
       "-e", "HOST_REMOTIVE_CONFIG_DIR=${configDir}",
       "-e", "REMOTIVE_CLOUD_ORGANIZATION=${env:REMOTIVE_CLOUD_ORGANIZATION}",
       "-e", "REMOTIVE_CLOUD_AUTH_TOKEN=${env:REMOTIVE_CLOUD_AUTH_TOKEN}",
       "-it", "remotivelabs/remotive-topology:latest"
   )
 
   docker $dockerParams @Args
}

Restart PowerShell.

Editor setup

RemotiveTopology uses yaml files to describe instances and platforms. It's strongly recommended that you configure RemotiveTopology json schema in your editor to make it easier to edit these files.

Visual Studio Code

Install Red Hat yaml plugin

Add the following to your settings.json:

    "yaml.schemas": {
        "https://files.remotivelabs.com/remotive_topology/topology-0.8.schema.json":
        ["*.instance.yaml", "*.platform.yaml"]
    },

Usage

Run the following to get further instructions:

remotive-topology --help

See Getting started for next steps.

Using RemotiveTopology in a CI environment

When running RemotiveTopology in a CI (Continuous Integration) environment, avoid using personal tokens. Instead, use a service account to ensure secure and maintainable access.

To create a service account, you must be an administrator of the relevant cloud project. If you created a personal account to evaluate RemotiveCloud or RemotiveTopology, you are automatically the administrator of that personal project.

You can create a service account in the RemotiveCloud console or by using RemotiveCli. In order to run RemotiveTopology, grant the RemotiveTopology Executor role to the service account.

To create the service account in the CLI:

# Check your project name
remotive cloud projects list
# Create the service account
remotive cloud service-accounts create <service account name> --role org/topologyRunner --project <project id>

Before using your service account to run RemotiveTopology, a token must be created. It's also necessary to know the id of the RemotiveCloud organization. You can use RemotiveCli to do this:

# Create the access token for the service account
remotive cloud service-accounts tokens create --service-account <service account name> --project <project id>
# Find the email of the service account
remotive cloud service-accounts list --project=<project id>
# Print the access token for the service account
remotive cloud auth print-access-token --account <email for service account>

# Find the uid of the organization
remotive cloud organizations list

With this information, the following environment variables can be used to handle access to RemotiveCloud and validation of the RemotiveTopology subscription

• REMOTIVE_CLOUD_AUTH_TOKEN - Provides an authentication token.
• REMOTIVE_CLOUD_ORGANIZATION - Provides your RemotiveCloud organization.

RemotiveCLI provides more commands to handle service accounts and tokens. More information can be found in the Service Accounts section in the RemotiveCLI documentation.

Important

It's important that you run all remotive-topology commands at the root of your project folder. This allows all files to be accessed correctly inside the docker container. This also includes all output folders!

• Don't use absolute paths
• Don't use ..

On Windows: since remotive-topology is running in a docker container using Linux you might encounter some unexpected warnings or errors. Your files are mounted inside the container using current working directory to the /data folder. This means that you might see error messages referring to files /data/something/somefile.instance.yaml. Remember that this means that your actual file is located ./something/somefile.instance.yaml!