Service

Represents a long-running background service deployment on Datatailr.

A service runs continuously (e.g., an API server, a message consumer, or any always-on process). It is restarted automatically if it exits.

Example

from datatailr import Service

# service.py
from flask import Flask

app = Flask(__name__)

@app.route("/health")
def health_check():
    return "OK"

# Service entrypoints receive the port from Datatailr.
def run_server(port):
    app.run("0.0.0.0", port=int(port), debug=False)

svc = Service(
    name="Simple Service",
    entrypoint=run_server,
    python_requirements=["flask"],
)
svc.run()

Parameters:

• name

  (str) –

  Display name for the service.

• entrypoint

  (Callable) –

  The callable (function) that starts the service.

• environment

  (Environment | None, default: DEV ) –

  Target environment for the deployment.

• image

  (Image | None, default: None ) –

  Pre-configured container Image.

• run_as

  (str | User | None, default: None ) –

  User or username to run the service as.

• resources

  (Resources | None, default: None ) –

  CPU and memory resources for the container. Defaults to Resources().

• acl

  (ACL | None, default: None ) –

  Access control list.

• python_version

  (str, default: '3.12' ) –

  Python version for the container image.

• python_requirements

  (str | list[str], default: '' ) –

  Python dependencies (see Image).

• build_script_pre

  (str, default: '' ) –

  Dockerfile commands to run before installing requirements.

• build_script_post

  (str, default: '' ) –

  Dockerfile commands to run after installing requirements.

• env_vars

  (dict[str, str | int | float | bool] | None, default: None ) –

  Environment variables passed to the running container.

• get_existing

  (bool, default: False ) –

  If True, update an existing job definition.

• version

  (str | int | None, default: None ) –

  The version of the job to get.

• budget

  (Budget | str | None, default: None ) –

  Optional spend budget as Budget("name") or a name str. Will be set to the 'default' budget if not provided.

instant_run

Run the service immediately using the workstation runner image.

Same buildless path as :meth:Workflow.instant_run: submit as the {workstation}--runner per-user job so the scheduler forks a unique run ({runner}-{uuid}) that reuses the already-built runner image. After a successful call, :attr:_internal_name is the forked service name (use that for DNS / client connections).

Parameters:

• instant_run_mode

  (str, default: 'source' ) –

  Entry-point transport strategy.

  • "source" (default): bundle the entrypoint module tree and extract it into the runner image at start time.
  • "preinstalled": no bundling; the entrypoint must already exist on the workstation image (e.g. datatailr.joblib).
  • "auto": resolves to "source".
  • "cloudpickle": not supported for services.

• image_from_workstation

  (str | None, default: None ) –

  Workstation job name whose --runner image should be used. Defaults to DATATAILR_JOB_NAME or default-workstation.

Returns:

• tuple[bool, str] –

  A tuple of (success, message).

Examples:

User service with source bundling:

from datatailr import Service
from my_service import run_server

svc = Service(name="My Service", entrypoint=run_server)
ok, _ = svc.instant_run(instant_run_mode="source")

Preinstalled entrypoint (joblib broker style):

from datatailr import Service
from datatailr.joblib._broker import main as broker_main

svc = Service(name="joblib-broker", entrypoint=broker_main)
ok, _ = svc.instant_run(instant_run_mode="preinstalled")
broker_name = svc._internal_name  # forked unique name