Command¶

A command is the specification for a container that can be started interactively by the user. This is used to start CLI command containers.

Commands can either be invoked via riptide cmd or directly via Riptide’s shell integration.

Commands either run as separate containers in the same container network as services (normal commands), or are started in running service containers.

Schema¶

The Schema defines what the contents of the YAML configuration files are.

classmethod schema() → schema.Schema¶: Can be either a normal command, a command in a service, or an alias command.

classmethod schema_normal()¶

Normal commands are executed in seperate containers, that are running in the same container network as the services.

[$name]: str

Name as specified in the key of the parent app.

Added by system. DO NOT specify this yourself in the YAML files.

image: str

Docker Image to use

[command]: str

Command to run inside of the container. Default’s to command defined in image.

Warning

Avoid quotes (”, ‘) inside of the command, as those may lead to strange side effects.

[additional_volumes]

Additional volumes to mount into the container for this command.

{key}

host: str: Path on the host system to the volume. Avoid hardcoded absolute paths.
container: str: Path inside the container (relative to src of Project or absolute).
[mode]: str: Whether to mount the volume read-write (“rw”, default) or read-only (“ro”).
[type]: str: Whether this volume is a “directory” or a “file”. If the file does not exist on the host, Riptide will create as specified. If not defined, Riptide will create a directory if it does not exist on the host. Only if it is defined Riptide will also check that an existing file also matches this definition (i.e. Riptide will error if this is set to “file” but “host” points to a directory and vice versa).
[volume_name]: str: Name of a named volume for this additional volume. Used instead of “host” if present and the dont_sync_named_volumes_with_host performance setting is enabled. Volumes with the same volume_name have the same content, even across projects. As a constraint, the name of two volumes should only be the same, if the host path specified is also the same, to ensure the same behaviour regardless of if the performance setting is enabled.
[host_system]: Or[‘Linux’, ‘Darwin’, ‘Windows’]: Only mount this volume if the host system name <https://docs.python.org/3/library/platform.html#platform.system> matches this value.

[environment]

Additional environment variables

{key}: str: Key is the name of the variable, value is the value.

[config_from_roles]: List[str]

List of role names. All files defined under “config” for services matching the roles are mounted into the command container.

[read_env_file]: bool

If enabled, read the environment variables in the env-files defined in the project (env_files). Default: True

[use_host_network]: bool

If enabled, the container uses network mode host. Overrides network and port settings Default: False

[ignore_original_entrypoint]: bool

If true, Riptide will not run the original entrypoint of the OCI image, but instead run the command directly, as if no entrypoint was defined in the image. Note that engines might ignore this setting, if they don’t support it.

Default: False

Example Document:

command:
  image: riptidepy/php
  command: 'php index.php'

classmethod schema_in_service()¶

Command is run in a running service container.

If the service container is not running, a new container is started based on the definition of the service.

[$name]: str

Name as specified in the key of the parent app.

Added by system. DO NOT specify this yourself in the YAML files.

in_service_with_role: str

Runs the command in the first service which has this role.

May lead to unexpected results, if multiple services match the role.

command: str

Command to run inside of the container.

Warning

Avoid quotes (”, ‘) inside of the command, as those may lead to strange side effects.

[environment]

Additional environment variables. The container also has access to the environment of the service. Variables in the current user’s env will override those values and variables defined here, will override all other.

{key}: str: Key is the name of the variable, value is the value.

[read_env_file]: bool

If enabled, read the environment variables in the env-files defined in the project (env_files). Default: True

[use_host_network]: bool

If enabled, the container uses network mode host. Overrides network and port settings Default: False

[ignore_original_entrypoint]: bool

Default: False

Example Document:

command:
  in_service_with_role: php
  command: 'php index.php'

classmethod schema_alias()¶

Aliases another command.

[$name]: str

Name as specified in the key of the parent app.

Added by system. DO NOT specify this yourself in the YAML files.

aliases: str

Name of the command that is aliased by this command.

Helper Functions¶

Helper Functions (also called “Variable Helpers”) can be used in the configuration files to perform some advanced tasks.

parent() → riptide.config.document.app.App | None¶

Returns the app that this belongs to.

Example usage:

something: '{{ parent().notices.usage }}'

Example result:

something: 'This is easy to use.'

system_config() → riptide.config.document.config.Config¶

Returns the system configuration.

Example usage:

something: '{{ system_config().proxy.ports.http }}'

Example result:

something: '80'

volume_path() → str¶

Returns the (host) path to a command-unique directory for storing container data.

Example usage:

additional_volumes:
    command_cache:
        host: '{{ volume_path() }}/command_cache'
        container: '/foo/bar/cache'

Example result:

additional_volumes:
    command_cache:
        host: '/home/peter/my_projects/project1/_riptide/cmd_data/command_name/command_cache'
        container: '/foo/bar/cache'

os_user() → str¶

Returns the user id of the current user as string (or 0 under Windows).

This is the same id that would be used if “run_as_current_user” was set to true.

Example usage:

something: '{{ os_user() }}'

Example result:

something: '1000'

os_group() → str¶

Returns the id of the current user’s primary group as string (or 0 under Windows).

This is the same id that would be used if “run_as_current_user” was set to true.

Example usage:

something: '{{ os_group() }}'

Example result:

something: '100'

host_address() → str¶

Returns the hostname that the host system is reachable under inside the container.

Example usage:

something: '{{ host_address() }}'

Example result:

something: 'host.riptide.internal'

home_path() → str¶

Returns the path to the home directory inside the container.

Example usage:

something: '{{ home_path() }}'

Example result:

something: '/home/riptide'

get_tempdir() → str¶

Returns the path to the system (host!) temporary directory where the user (should) have write access.

Example usage:

something: '{{ get_tempdir() }}'

Example result:

something: '/tmp'