Services¶

A service is the definition of a software container that contains one of the applications required to run the entire app.

Since services are container definitions, they need to contain at least the name of an image to run. All other fields are optional.

Schema¶

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

classmethod Service.schema() → schema.Schema[source]¶

[$name]: str

Name as specified in the key of the parent app.

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

[roles]: List[str]

A list of roles for this service. You can use arbitrary strings and get services by their assigned roles using get_service_by_role().

Some roles are pre-defined and have a special meaning:

main:

This service is the main service for the app.

Some commands will default to this service and the proxy URL for this service is shorter. Usually services are accessible via http://<project_name>--<service_name>.<proxy_url>, however the main service is accessible via http://<project_name>.<proxy_url>.

Only one service is allowed to have this role.

src:

The container of this service will have access to the source code of the application.

It’s working directory will be set accordingly.

db:

This service is the primary database. A database driver has to be set (see key driver).

This service is then used by Riptide for database management </user_docs/db.html>.

image: str

Docker Image to use

[command]: str or map

If this is not set:

The default command in the image is used and considered in the “default” command group (see below).

If it is a string:

Command to run inside of the container. Default’s to command defined in image. This command will be in the “default” command group (see below).

If it is a map:

A list of commands that this service supports. Keys are the “command group”, values the commands to run. Each service must have a command defined for the “default” command group. You can speficy a command group to use when using riptide start. Default is the “default” command group, this one is also used by the Riptide Proxy autostart feature. For more information on this see the –cmd flag of riptide start.

Example:

comamnd:
  default: "npm run default"
  debug: "npm run debug"

Warning

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

[port]: int

HTTP port that the web service is accessible under. This port will be used by the proxy server to redirect the traffic.

If the port is not specified, the service is not accessible via proxy server.

[logging]

Logging settings. All logs will be placed inside the “_riptide/logs” directory.

[stdout]: bool

Whether or not to log the stdout stream of the container’s main command. Default: false

[stderr]: bool

Whether or not to log the stderr stream of the container’s main command. Default: false

[paths]

{key}: str: Additional text files to mount into the logging directory. Keys are filename’s on host (without .log) and values are the paths inside the containers.

[commands]

{key}: str: Additional commands to start inside the container. Their stdout and stderr will be logged to the file specified by the key.

[pre_start]: List[str]

List of commands to run, before the container starts. They are run sequentially. The startup will wait for the commands to finish. Exit codes (failures) are ignored.

Each of these commands is run in a separate container based on the service specification. Each command is run in a “sh” shell.

[post_start]: List[str]

List of commands to run, after container starts. They are run sequentially. The startup will wait for the commands to finish. Exit codes (failures) are ignored.

Each of these command’s is run inside the service container (equivalent of docker exec). Each command is run in a “sh” shell.

[environment]

Additional environment variables

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

[working_directory]: str

Working directory for the service, either

absolute, if an absolute path is given
relative to the src specified in the project, if the role “src” is set.
relative to the default working directory from the image, if the role is not set.

Defaults to ..

[config]

Additional configuration files to mount. These files are NOT directly mounted. Instead they are processed and the resulting file is mounted.

All variables and variable helpers inside the configuration file are processed.

Processed config files are either written to _riptide/processed_config and mounted to containers or (if they are under the source tree of the project and the service has the role ‘src’) copied to the path in the project and mounted with the rest of the source tree. A ‘.riptide_info.txt’ is added then to explain the origin of this file.

Example configuration file (demo.ini):

[demo]
domain={{domain()}}
project_name={{parent().parent().name}}

Resulting file that will be mounted:

[demo]
domain=projectname.riptide.local
project_name=projectname

{key}

from: str: Path to the configuration file, relative to any YAML file that was used to load the project (including “riptide.yml” and all yaml files used inside the repository; all are searched). Absolute paths are not allowed.
to: str: Path to store the configuration file at, relative to working directory of container or absolute.
[force_recreate: bool]: False by default. If false, command containers that use this config file will not try to recreate the processed file if it already exists. If true command containers will also recreate the file every time they are started. Started services always recreate the processed file on start, regardless of this setting.

[additional_ports]

Additional TCP and/or UDP ports that will be made available on the host system. For details see section in user guide.

{key}

title: str: Title for this port, will be displayed in riptide status
container: int: Port number inside the container
host_start: int: First port number on host that Riptide will try to reserve, if the port is already occupied, the next one will be used. This port will be reserved and permanently used for this service after that.

[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” (default) or a “file”. Only checked if the file/dir does not exist yet on the host system. Riptide will then create it with the appropriate type.
[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.

[driver]

The database driver configuration, set this only if the role “db” is set.

Detailed documentation can be found in a separate section.

name: str: Name of the database driver, must be installed.
config: ???: Specification depends on the database driver.

[run_as_current_user]: bool

Whether to run as the user using riptide (True) or image default (False).

Default: True

Riptide will always create the user and group, matching the host user and group, inside the container on startup, regardless of this setting.

Some images don’t support switching the user, set this to false then. Please note that, if you set this to false and also specify the role ‘src’, you may run into permission issues.

[run_pre_start_as_current_user]: ‘auto’ or bool

Whether to run pre start commands the user using riptide or image default. Default is ‘auto’ which means the value of run_as_current_user will be used.

[run_post_start_as_current_user]: ‘auto’ or bool

Whether to run post start commands the user using riptide or image default. Default is ‘auto’ which means the value of run_as_current_user will be used.

[allow_full_memlock]: bool

Whether to set memlock ulimit to -1:-1 (soft:hard). This is required for some database services, such as Elasticsearch. Note that engines might ignore this setting, if they don’t support it.

Default: False

[read_env_file]: bool

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

Example Document:

service:
  image: node:10
  roles:
    - main
    - src
  command: 'node server.js'
  port: 1234
  logging:
    stdout: true
    stderr: false
    paths:
      one: '/foo/bar'
    commands:
      two: 'varnishlog'
  pre_start:
    - "echo 'command 1'"
    - "echo 'command 2'"
  post_start:
    - "echo 'command 3'"
    - "echo 'command 4'"
  environment:
    SOMETHING_IMPORTANT: foo
  config:
    one:
      from: ci/config.yml
      to: app_config/config.yml
  working_directory: www
  additional_ports:
    one:
      title: MySQL Port
      container: 3306
      host_start: 3006
  additional_volumes:
    temporary_files:
      host: '{{ get_tempdir() }}'
      container: /tmp

Helper Functions¶

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

Service.parent() → App[source]¶

Variable Helper

Can be used inside configuration files.

Returns the app that this service belongs to.

Example usage:

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

Example result:

something: 'This is easy to use.'

Service.system_config() → Config¶

Variable Helper

Can be used inside configuration files.

Returns the system configuration.

Example usage:

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

Example result:

something: '80'

Service.volume_path() → str[source]¶

Variable Helper

Can be used inside configuration files.

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

Example usage:

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

Example result:

additional_volumes:
    cache:
        host: '/home/peter/my_projects/project1/_riptide/data/service_name/cache'
        container: '/foo/bar/cache'

Service.get_working_directory() → str[source]¶

Variable Helper

Can be used inside configuration files.

Returns the path to the working directory of the service inside the container.

Warning

Does not work as expected for services started via “start-fg”.

Example usage:

something: '{{ get_working_directory() }}'

Example result:

something: '/src/working_dir'

Service.domain() → str[source]¶

Variable Helper

Can be used inside configuration files.

Returns the full domain name that this service should be available under, without protocol. This is the same domain as used for the proxy server.

Example usage:

something: 'https://{{ domain() }}'

Example result:

something: 'https://project--service.riptide.local'

Service.os_user() → str¶

Variable Helper

Can be used inside configuration files.

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'

Service.os_group() → str¶

Variable Helper

Can be used inside configuration files.

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'

Service.host_address() → str¶

Variable Helper

Can be used inside configuration files.

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

Example usage:

something: '{{ host_address() }}'

Example result:

something: 'host.riptide.internal'

Service.home_path() → str¶

Variable Helper

Can be used inside configuration files.

Returns the path to the home directory inside the container.

Example usage:

something: '{{ home_path() }}'

Example result:

something: '/home/riptide'

Service.get_tempdir() → str¶

Variable Helper

Can be used inside configuration files.

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'

Helpfer Functions for configuration files¶

The helper functions listed here can only be used inside files used with the config setting of services.

riptide.config.service.config_files_helper_functions.read_file(config_file_path: str, file_to_read_in: str) → str[source]¶

Reads the contents of a file, relative to the configuration file being processed.

Can not access files in parent directories. Variables in the included file are not processed.

The parameter config_file_path is automatically filled by Riptide.

Example usage:

{{ read_file('example.txt') }}

Example result:

contents of example.txt