Welcome to the Telesto documentation

Installation

Telesto is open source software released under the MIT License and is installable as a Python package. For installation instructions and to view the source code, see https://codeberg.org/visual-topology/telesto.

Introduction - Basic Concepts

Command Line Interface

Launch telesto using:

telesto [options]

Where [options] are defined as follows:

Web server options:

option	description
--host	Specify the host name at which the service will listen
--port	Specify the port number at which the service will listen
--base-url	Specify the base-url at which the service will listen

Workspace configuration options:

Telesto is configured with at least one workspace.

Each workspace is defined using a TOML configuration file, and is associated with a filesystem location for storing topologies and a set of packages implementing nodes.

option	description
--configuration [,...]	Specify the path(s) to configuration file(s) for each workspace
--generate-example-configuration	Generate a sample workspace configuration file to this path and then exit
--workspace-root-folder	Specify a root folder for workspaces
--main-workspace-id	If multiple workspaces are defined, specify a main one

A sample configuration file created by running with the option --generate-example-configuration :

# configuration for a set of telesto applications

workspace_id = "primary_workspace"
workspace_name="Primary Workspace"
workspace_description="Primary Workspace Description"
workspace_path="primary_workspace_folder"

# this workspace will automatically include packages defined using the entrypoint telesto_packages

# specify import paths for additional topology package to load
include_packages = []

# specify patterns to select topology packages to exclude
exclude_packages = []

# close topology runners if idle for more than 60 seconds
idle_timeout = 60

directory_title = "Telesto Directory"
designer_title = "Telesto Designer"

[directory_splash]

title = "Telesto Directory - Loading..."
image_url = "static/icons/telesto.svg"

[designer_splash]

title = "Telesto Designer"
image_url = "static/icons/telesto.svg"

The --workspace-root-folder option is used to provide a base filesystem path under which workspaces with the workspace_path set to a relative path are located.

Where multiple workspaces are configured, the main workspace identified with --main-workspace-id is selected to launch in desktop mode (see below) and also available via the shortcut <host>:<port>/<base-url>

Desktop mode

Desktop mode allows telesto to be run on a desktop/laptop, automatically launching a web-browser locally.

option	description
--launch-ui	specify a command to launch a web browser on startup, for example \"chromium --app=URL\". URL will be substituted for the url of the main workspace's directory.

Telesto Packages

Telesto Packages defined bundles of nodes which can be arranged into topologies, and are based on hyrrokkin packages.

Telesto will load packages into each workspace according to:

• Any packages defined using the telesto_packages entrypoint. These are defined in the python packaging, for example in pyproject.toml. This allows packages to be automatically detected if they are installed using pip.

[project.entry-points.telesto_packages]
textgraph = "telesto.example_packages.textgraph"

• Any packages defined in the workspace configuration's include_packages option
• Any packages defined using the --include-packages command line option

Both include_packages and --include_packages specify packages in python's "dotted path" notation, eg <package>[.<sub-package>] and should resolve to the folder containing the package's schema.json file.

However, packages will be excluded if:

• the package's "dotted path" matches a pattern defined in --exclude-packages command line option
• the package's "dotted path" matches a pattern defined in thw workspace configuration's exclude_packages command line option

option	description
--include-packages	Add these packages to each workspace
--exclude-packages	Exclude packages matching this pattern (use * as a wildcard) from each workspace

Miscellaneous options:

option	description
--verbose	print verbose output to the console
--monitoring	Enable narvi service monitoring with the specified interval and retention period (in seconds) set either to zero to disable monitoring
--in-process	If possible, run all topologies within the server process. Usually topologies are run in sub-processes for better isolation.
--use-server auto | tornado | builtin	Choose the web-server to use. Defaults to auto, meaning use tornado if installed, otherwise fallback to a builtin web-server

Templates

The configuration file allows the definition of template topologies. The snippet below will automatically add a topology with id example by loading from the example.zip file located in the python package telesto.example_packages.textgraph.topologies

[template.example]
import_path = "telesto.example_packages.textgraph.topologies.example.zip"

Note that a user may modify a topology loaded from a template, but not remove it. The directory application UI will provide a reload button that will reload the topology from the zip file, discarding any edits.

Applications

Applications are custom web-apps which allow the user to interact with a topology

name="Test Application"
description="Test Application Description"
topology_id="example"
application_package="telesto.custom_apps.demo_auto_tile"