1. Docs
  2. Self-Hosted
  3. Configuring Tines

Run Script (tines-command-runner)

Last updated Open markdown version

This page documents how to configure your tines-command-runner instance using environment variables. For platform-specific deployment instructions, consult our guides to deploying tines-command-runner with AWS Fargate or Docker Compose, or use our Helm charts to deploy to Kubernetes.

Configuring tines-command-runner

Tines-command-runner exposes settings for controlling Run Script action execution using environment variables. See the platform-specific pages linked above for more on setting environment variables in tines-command-runner using your platform of choice.

Basic settings

  • LOG_LEVEL - Configures the logging level for the Python harness. Set to DEBUG, INFO, WARNING, ERROR, or CRITICAL (default: INFO). Set LOG_LEVEL=DEBUG to enable verbose debug logging for troubleshooting. Logs are written to /tmp/tcr-logs/harness-{environment_id}-{stdout,stderr}.log.

Package indexes

These settings can be changed to use your own, custom index for Python packages.

  • PIP_INDEX_URL - Specifies the primary Python package index used for package resolution and download. Default: https://pypi.org/simple.

  • PIP_EXTRA_INDEX_URL - Specifies a fallback Python package index to be used if the primary index is offline or missing a desired package. Default: http://pypi-server:8080/simple/, a local pypi server that runs alongside your tines-command-runner container.

  • NO_PIP_INDEX - If set to true, blocks access to all package indexes, even if they are specified by PIP_INDEX_URL or PIP_EXTRA_INDEX_URL, restricting dependencies to those bundled with the Python image (see "Pre-installed packages" below).

  • TRUSTED_HOST - A hostname for a package index that can be accessed via unsecured HTTP when fetching packages. Default: pypi-server

Pre-installed packages

The Python packages below are included in our bundled Python image by default. These packages are available even if NO_PIP_INDEX=true. More packages may be added to this list in the future, and the installed version of these packages may change.

These packages are not available by default to user-provided custom runtimes. Custom runtimes are fully self-contained and must bundle all required dependencies.

annotated-types
anyio
beautifulsoup4
boto
boto3
click
cryptography
django
fastapi
flask
grpcio
grpcio-reflection
grpcio-tools
h11
idna
jupyter
lxml
matplotlib
networkx
nltk
numpy
openpyxl
pandas
paramiko
plotly
protobuf
pyarrow
pyopenssl
pydantic
pydantic_core
pytest
pytz
requests
scikit-learn
scipy
seaborn
setuptools
sniffio
sqlalchemy
starlette
statsmodels
sympy
typing_extensions
uvicorn
xlrd

Note: All transitive dependencies required by the above packages are also automatically downloaded and available for use. This means the actual number of available packages is larger than this explicit list, as each package brings in its own required dependencies during the build process.

Performance and scaling

Timeouts

  • RUN_SCRIPT_MAX_TIMEOUT - Controls the maximum runtime of scripts. Scripts running for longer than this number of seconds will be killed, and the task will be marked as a failure. Default: 60 (sixty seconds)

Parallel execution

By default, each run-script action on a container can run two tasks concurrently before further tasks begin to queue, and a tines-command-runner container can run up to ten concurrent tasks in total before tasks for any environment will begin to queue. You can increase the number of parallel executions by either adding more containers or increasing the parallel execution limit within the container. Scaling containers vertically is recommended over scaling horizontally with multiple containers when possible. Vertical scaling improves initial execution time for new actions, reduces required disk space, and can better handle high throughput with less risk of being overwhelmed by bursts of tasks consuming significant resources.

Configuration

  • TINES_COMMAND_RUNNER_PARALLEL_RUNS controls the number of tasks a given action can run concurrently. Tasks for that action that are submitted while this many tasks are running will queue until a running task completes. Default: 2

  • TINES_COMMAND_RUNNER_THREADS controls the total number of tasks the tines-command-runner container can run at once. If more tasks come in while this many tasks are running, runs will begin to queue regardless of whether the requested action has reached the limit set by TINES_COMMAND_RUNNER_PARALLEL_RUNS. Default: 10

  • TCR_ENABLE_PARALLEL_CUSTOM_ENVIRONMENTS enables parallel execution for custom runtimes when set to true. Make sure your scripts run safely when running concurrently before enabling this. When enabled, custom runtimes will be limited to the number of concurrent runs specified in TINES_COMMAND_RUNNER_PARALLEL_RUNS. Default: false

Multi-container deployments

Tines-command-runner includes features that rely on information kept locally on a container. If you are running run script actions that use custom runtimes and you plan to run multiple replicas/pods/tasks for tines-command-runner, you may need to take some additional steps to ensure custom runtimes work correctly.

If you are not using custom runtimes, or you are running only one tines-command-runner instance, there are no additional steps needed.

The steps below are broken down by deployment platform.

Kubernetes

If you're deploying using our Helm charts, no further steps are needed. Tines-command-runner is configured correctly out of the box.

If you're deploying using custom Kubernetes resources or in-house Helm charts, ensure that you have a Service configured for tines-command-runner that has spec.sessionAffinity set to ClientIP. The timeout can be tuned to your liking, but should be at least fifteen minutes. If you are running a custom proxy that handles routing inbound traffic to tines-command-runner, you'll need to ensure that it behaves equivalently to the above session affinity setting (i.e. requests from the same tines-app pod are routed to the same tines-command-runner pod for 15 minutes or longer).

Docker Compose

Docker Compose does not support sticky sessions, so we recommend using only a single tines-command-runner task in your deployment with resources increased as needed to handle higher throughput. Use the environment variables in the Parallel Execution section above to tune the max parallel execution settings for your single instance of tines-command-runner.

If multiple tasks are required for your use case (e.g. for high-availability requirements), then you must configure a proxy to handle session management. We suggest using Traefik Proxy, which has guidance on configuring sticky sessions here.

AWS ECS

If you are following our recommended architecture and running tines-command-runner as a sidecar for your tines-sidekiq service, no further steps are needed.

If you are running a custom architecture and run tines-command-runner as a separate ECS service, ensure that you are using an application load balancer to route traffic to your tines-command-runner service, and update the settings for that load balancer to enable cookie stickiness (refer to the AWS documentation), with an expiration period of at least 15 minutes (900 seconds).

Was this helpful?