7.3. Command line interface#

This page contains the API reference of the functions in the vantage package. This package contains the Command-Line Interface (CLI) of the Vantage6 framework.

7.3.1. Node CLI#

vantage6.cli.node#

vnode#

The vnode commands allow you to manage your vantage6 node instances.

vnode [OPTIONS] COMMAND [ARGS]...

attach#

Show the node logs in the current console.

vnode attach [OPTIONS]

Options

-n, --name <name>#: Configuration name

--system#: Search for configuration in system folders rather than user folders

--user#: Search for configuration in user folders rather than system folders. This is the default

clean#

Erase temporary Docker volumes.

vnode clean [OPTIONS]

create-private-key#

Create and upload a new private key

Use this command with caution! Uploading a new key has several consequences, e.g. you and other users of your organization will no longer be able to read the results of tasks encrypted with current key.

vnode create-private-key [OPTIONS]

Options

-n, --name <name>#: Configuration name

-c, --config <config>#: Absolute path to configuration-file; overrides NAME

--system#: Search for configuration in system folders rather than user folders

--user#: Search for configuration in user folders rather than system folders. This is the default

--no-upload#: Don’t upload the public key to the server

-o, --organization-name <organization_name>#: Organization name. Used in the filename of the private key so that it can easily be recognized again later

--overwrite#: Overwrite existing private key if present

files#

Prints the location of important node files.

If the specified configuration cannot be found, it exits. Otherwise it returns the absolute path to the output.

vnode files [OPTIONS]

Options

-n, --name <name>#: Configuration name

--system#: Search for the configuration in the system folders

--user#: Search for the configuration in the user folders. This is the default

list#

Lists all node configurations.

Note that this command cannot find node configuration files in custom directories.

vnode list [OPTIONS]

new#

Create a new node configuration.

Checks if the configuration already exists. If this is not the case a questionnaire is invoked to create a new configuration file.

vnode new [OPTIONS]

Options

-n, --name <name>#: Configuration name

--system#: Store this configuration in the system folders

--user#: Store this configuration in the user folders. This is the default

remove#

Delete a node permanently.

Remove the configuration file, log file, and docker volumes attached to the node.

vnode remove [OPTIONS]

Options

-n, --name <name>#: Configuration name

--system#: Search for configuration in system folders rather than user folders

--user#: Search for configuration in user folders rather than system folders. This is the default

-f, --force#: Don’t ask for confirmation

set-api-key#

Put a new API key into the node configuration file

vnode set-api-key [OPTIONS]

Options

-n, --name <name>#: Configuration name

--api-key <api_key>#: New API key

--system#: Search for configuration in system folders rather than user folders

--user#: Search for configuration in user folders rather than system folders. This is the default

start#

Start the node.

vnode start [OPTIONS]

Options

-n, --name <name>#: Configuration name

-c, --config <config>#: Absolute path to configuration-file; overrides NAME

--system#: Search for the configuration in the system folders

--user#: Search for the configuration in the user folders. This is the default

-i, --image <image>#: Node Docker image to use

--keep, --auto-remove#: Keep node container after finishing. Useful for debugging

--force-db-mount#: Always mount node databases; skip the check if they are existing files.

--attach, --detach#: Show node logs on the current console after starting the node

--mount-src <mount_src>#: Override vantage6 source code in container with the source code in this path

stop#

Stop one or all running nodes.

vnode stop [OPTIONS]

Options

-n, --name <name>#: Configuration name

--system#: Search for configuration in system folders instead of user folders

--user#: Search for configuration in the user folders instead of system folders. This is the default.

--all#: Stop all running nodes

--force#: Kill nodes instantly; don’t wait for them to shut down

version#

Returns current version of a vantage6 node.

vnode version [OPTIONS]

Options

-n, --name <name>#: Configuration name

--system#: Search for configuration in system folders rather than user folders

--user#: Search for configuration in user folders rather than system folders. This is the default

7.3.2. Server CLI#

vserver#

The vserver commands allow you to manage your vantage6 server instances.

vserver [OPTIONS] COMMAND [ARGS]...

attach#

Show the server logs in the current console.

vserver attach [OPTIONS]

Options

-n, --name <name>#: configuration name

--system#

--user#

files#

List files that belong to a particular server instance.

vserver files [OPTIONS]

Options

-n, --name <name>#: Name of the configuration you want to use.

-c, --config <config>#: Absolute path to configuration-file; overrides NAME

--system#: Use system folders instead of user folders. This is the default

--user#: Use user folders instead of system folders

import#

Import vantage6 resources, such as organizations, collaborations, users and tasks into a server instance.

The FILE_ argument should be a path to a yaml file containing the vantage6 formatted data to import.

vserver import [OPTIONS] FILE

Options

--drop-all#: Drop all existing data before importing

-i, --image <image>#: Node Docker image to use

--mount-src <mount_src>#: Override vantage6 source code in container with the source code in this path

--keep, --auto-remove#: Keep image after finishing. Useful for debugging

--wait <wait>#: Wait for the import to finish

-n, --name <name>#: Name of the configuration you want to use.

-c, --config <config>#: Absolute path to configuration-file; overrides NAME

--system#: Use system folders instead of user folders. This is the default

--user#: Use user folders instead of system folders

Arguments

FILE#: Required argument

list#

Print the available server configurations.

vserver list [OPTIONS]

new#

Create a new server configuration.

vserver new [OPTIONS]

Options

-n, --name <name>#: name of the configuration you want to use.

--system#

--user#

shell#

Run an iPython shell within a running server. This can be used to modify the database.

NOTE: using the shell is no longer recommended as there is no validation on the changes that you make. It is better to use the Python client or a graphical user interface instead.

vserver shell [OPTIONS]

Options

-n, --name <name>#: Name of the configuration you want to use.

-c, --config <config>#: Absolute path to configuration-file; overrides NAME

--system#: Use system folders instead of user folders. This is the default

--user#: Use user folders instead of system folders

start#

Start the server.

vserver start [OPTIONS]

Options

--ip <ip>#: IP address to listen on

-p, --port <port>#: Port to listen on

-i, --image <image>#: Server Docker image to use

--with-ui#: Start the graphical User Interface as well

--ui-port <ui_port>#: Port to listen on for the User Interface

--with-rabbitmq#: Start RabbitMQ message broker as local container - use in development only

--rabbitmq-image <rabbitmq_image>#: RabbitMQ docker image to use

--keep, --auto-remove#: Keep image after server has stopped. Useful for debugging

--mount-src <mount_src>#: Override vantage6 source code in container with the source code in this path

--attach, --detach#: Print server logs to the console after start

-n, --name <name>#: Name of the configuration you want to use.

-c, --config <config>#: Absolute path to configuration-file; overrides NAME

--system#: Use system folders instead of user folders. This is the default

--user#: Use user folders instead of system folders

stop#

Stop one or all running server(s).

vserver stop [OPTIONS]

Options

-n, --name <name>#: Configuration name

--system#

--user#

--all#: Stop all servers

version#

Print the version of the vantage6 server.

vserver version [OPTIONS]

Options

-n, --name <name>#: Configuration name

--system#

--user#

7.3.3. vantage6.cli.context#

The context module in the CLI package contains the definition of the ServerContext and NodeContext classes. These contexts are related to the host system and therefore part of the CLI package.

Both classes are derived from the abstract AppContext class. And provide the node and server with naming conventions, standard file locations, and in the case of the node with a local database URIs.

Server Context: A class to provide context for the server, both for development mode as for production.
Node Context: In case the node is run in development mode, this context will also used by the node package. Normally the node uses the vantage6.node.context.DockerNodeContext which provides the same functionality but is tailored to the Docker environment.

class NodeContext(instance_name, system_folders=False, config_file=None)#

Bases: AppContext

Node context

See DockerNodeContext for the node instance mounts when running as a dockerized service.

Parameters:

instance_name (str) – Name of the configuration instance, corresponds to the filename of the configuration file.
system_folders (bool, optional) – _description_, by default N_FOL
config_file (str, optional) – _description_, by default None

INST_CONFIG_MANAGER#: alias of NodeConfigurationManager

classmethod available_configurations(system_folders=False)#

Find all available server configurations in the default folders.

Parameters:: system_folders (bool, optional) – System wide or user configuration, by default N_FOL
Returns:: The first list contains validated configuration files, the second list contains invalid configuration files.
Return type:: tuple[list, list]

classmethod config_exists(instance_name, system_folders=False)#

Check if a configuration file exists.

Parameters:

instance_name (str) – Name of the configuration instance, corresponds to the filename of the configuration file.
system_folders (bool, optional) – System wide or user configuration, by default N_FOL

Returns:

Whether the configuration file exists or not

Return type:

bool

property databases: dict#

Dictionary of local databases that are available for this node.

Returns:: dictionary with database names as keys and their corresponding paths as values.
Return type:: dict

property docker_container_name: str#

Docker container name of the node.

Returns:: Node’s Docker container name
Return type:: str

property docker_network_name: str#

Private Docker network name which is unique for this node.

Returns:: Docker network name
Return type:: str

property docker_squid_volume_name: str#

Docker volume in which the SSH configuration is stored.

Returns:: Docker volume name
Return type:: str

property docker_ssh_volume_name: str#

Docker volume in which the SSH configuration is stored.

Returns:: Docker volume name
Return type:: str

docker_temporary_volume_name(job_id)#

Docker volume in which temporary data is stored. Temporary data is linked to a specific run. Multiple algorithm containers can have the same run id, and therefore the share same temporary volume.

Parameters:: job_id (int) – run id provided by the server
Returns:: Docker volume name
Return type:: str

property docker_volume_name: str#

Docker volume in which task data is stored. In case a file based database is used, this volume contains the database file as well.

Returns:: Docker volume name
Return type:: str

property docker_vpn_volume_name: str#

Docker volume in which the VPN configuration is stored.

Returns:: Docker volume name
Return type:: str

classmethod from_external_config_file(path, system_folders=False)#

Create a node context from an external configuration file. External means that the configuration file is not located in the default folders but its location is specified by the user.

Parameters:

path (str) – Path of the configuration file
system_folders (bool, optional) – System wide or user configuration, by default N_FOL

Returns:

Node context object

Return type:

NodeContext

get_database_uri(label='default')#

Obtain the database URI for a specific database.

Parameters:: label (str, optional) – Database label, by default “default”
Returns:: URI to the database
Return type:: str

static type_data_folder(system_folders=False)#

Obtain OS specific data folder where to store node specific data.

Parameters:: system_folders (bool, optional) – System wide or user configuration
Returns:: Path to the data folder
Return type:: Path

class ServerContext(instance_name, system_folders=True)#

Bases: AppContext

Server context

Parameters:

instance_name (str) – Name of the configuration instance, corresponds to the filename of the configuration file.
system_folders (bool, optional) – System wide or user configuration, by default S_FOL

INST_CONFIG_MANAGER#: alias of ServerConfigurationManager

classmethod available_configurations(system_folders=True)#

Find all available server configurations in the default folders.

Parameters:: system_folders (bool, optional) – System wide or user configuration, by default S_FOL
Returns:: The first list contains validated configuration files, the second list contains invalid configuration files.
Return type:: tuple[list, list]

classmethod config_exists(instance_name, system_folders=True)#

Check if a configuration file exists.

Parameters:

instance_name (str) – Name of the configuration instance, corresponds to the filename of the configuration file.
system_folders (bool, optional) – System wide or user configuration, by default S_FOL

Returns:

Whether the configuration file exists or not

Return type:

bool

property docker_container_name: str#

Name of the docker container that the server is running in.

Returns:: Server’s docker container name
Return type:: str

classmethod from_external_config_file(path, system_folders=True)#

Create a server context from an external configuration file. External means that the configuration file is not located in the default folders but its location is specified by the user.

Parameters:

path (str) – Path of the configuration file
system_folders (bool, optional) – System wide or user configuration, by default S_FOL

Returns:

Server context object

Return type:

ServerContext

get_database_uri()#

Obtain the database uri from the environment or the configuration. The VANTAGE6_DB_URI environment variable is used by the Docker container, but can also be set by the user.

Returns:: string representation of the database uri
Return type:: str

7.3.4. vanatge6.cli.configuration_manager#

class NodeConfiguration(*args, **kwargs)#

Bases: Configuration

Stores the node’s configuration and defines a set of node-specific validators.

class NodeConfigurationManager(name, *args, **kwargs)#

Bases: ConfigurationManager

Maintains the node’s configuration.

Parameters:: name (str) – Name of the configuration file.

classmethod from_file(path)#

Create a new instance of the NodeConfigurationManager from a configuration file.

Parameters:: path (str) – Path to the configuration file.
Returns:: A new instance of the NodeConfigurationManager.
Return type:: NodeConfigurationManager

class ServerConfiguration(*args, **kwargs)#

Bases: Configuration

Stores the server’s configuration and defines a set of server-specific validators.

class ServerConfigurationManager(name, *args, **kwargs)#

Bases: ConfigurationManager

Maintains the server’s configuration.

Parameters:: name (str) – Name of the configuration file.

classmethod from_file(path)#

Create a new instance of the ServerConfigurationManager from a configuration file.

Parameters:: path (str) – Path to the configuration file.
Returns:: A new instance of the ServerConfigurationManager.
Return type:: ServerConfigurationManager

class TestConfiguration(*args, **kwargs)#: Bases: Configuration

class TestingConfigurationManager(name, *args, **kwargs)#

Bases: ConfigurationManager

classmethod from_file(path)#

Load a configuration from a file.

Parameters:

path (Path | str) – The path to the file to load the configuration from.
conf_class (Type[Configuration]) – The class to use for the configuration.

Returns:

The configuration manager with the configuration.

Return type:

ConfigurationManager

Raises:

AssertionError – If the name of the configuration could not be extracted from the file path.

7.3.5. vantage6.cli.configuration_wizard#

configuration_wizard(type_, instance_name, system_folders)#

Create a configuration file for a node or server instance.

Parameters:

type (str) – Type of the instance. Either “node” or “server”
instance_name (str) – Name of the instance
system_folders (bool) – Whether to use the system folders or not

Returns:

Path to the configuration file

Return type:

Path

node_configuration_questionaire(dirs, instance_name)#

Questionary to generate a config file for the node instance.

Parameters:

dirs (dict) – Dictionary with the directories of the node instance.
instance_name (str) – Name of the node instance.

Returns:

Dictionary with the new node configuration

Return type:

dict

select_configuration_questionaire(type_, system_folders)#

Ask which configuration the user wants to use. It shows only configurations that are in the default folder.

Parameters:

type (str) – Type of the instance. Either “node” or “server”
system_folders (bool) – Whether to use the system folders or not

Returns:

Name of the configuration

Return type:

str

server_configuration_questionaire(instance_name)#

Questionary to generate a config file for the node instance.

Parameters:: instance_name (str) – Name of the node instance.
Returns:: Dictionary with the new server configuration
Return type:: dict

7.3.6. vanatge6.cli.rabbitmq.queue_manager#

class RabbitMQManager(ctx, network_mgr, image=None)#

Manages the RabbitMQ docker container

Parameters:

ctx (ServerContext) – Configuration object
network_mgr (NetworkManager) – Network manager for network in which server container resides
image (str) – Docker image to use for RabbitMQ container. By default, the image harbor2.vantage6.ai/infrastructure/rabbitmq is used.

is_running()#

Returns:: Whether the container has fully initialized RabbitMQ or not
Return type:: bool

start()#

Start a docker container which runs a RabbitMQ queue

Return type:: None

7.3.7. vanatge6.cli.rabbitmq#

RabbitMQ utilities.

split_rabbitmq_uri(rabbit_uri)#

Get details (user, pass, host, vhost, port) from a RabbitMQ uri.

Parameters:: rabbit_uri (str) – URI of RabbitMQ service (‘amqp://$user:$pass@$host:$port/$vhost’)
Returns:: The vhost defined in the RabbitMQ URI
Return type:: dict[str]

7.3.8. vantage6.cli.utils#

Utility functions for the CLI

check_config_name_allowed(name)#

Check if configuration name is allowed

Parameters:: name (str) – Name to be checked
Return type:: None

check_if_docker_daemon_is_running(docker_client)#

Check if Docker daemon is running

Parameters:: docker_client (docker.DockerClient) – The docker client
Return type:: None

prompt_config_name(name)#

Get a new configuration name from the user, or simply return the name if it is not None.

Parameters:: name (str) – Name to be checked
Returns:: The name of the configuration
Return type:: str

remove_file(file, file_type)#

Remove a file if it exists.

Parameters:

file (str) – absolute path to the file to be deleted
file_type (str) – type of file, used for logging

Return type:

None