Skip to main content

Quick start

BatchX images are implemented as Docker images with additional requirements. In this example, you will import an already-built image into your environment from Docker Hub.

Install the CLI​

As a preliminary step you will need to install the CLI if you haven't done it before.

Clone image​

In this first step will get the image batchx@tutorial/hello-world (BatchX coordinates) into your environment.

Use the bx clone command to import the image as follows:

bx clone batchx@tutorial/hello-world

View image details​

Once imported you can see the image listed in the image repository of your environment. Use the bx images command to list the images of your environment. You should obtain an output similar to the one below:

$ bx images
IMAGE                              CREATED       SIZE     SHARED   PRICE  DESCRIPTION         TAGS
batchx@tutorial/hello-world:1.0.3  8 months ago  27.5 MB          0.00 $  BatchX Hello World  tutorial

You can also, see the images details by running the bx imagecommand:

$ bx image batchx@tutorial/hello-world:1.0.3
--------------------------------------------------------------------------------
Details:
  Coordinates: batchx@tutorial/hello-world:1.0.3
  Tags: tutorial
  Author: BatchX
  Imported on: Sun Jun 27 18:09:18 CEST 2021
  Imported by: david
  Minimum memory: 1.0 GB
  GPUs: Not allowed
  Image size: 27.5 MB
  Versions: [1.0.3, 1.0.2, 1.0.1]
--------------------------------------------------------------------------------
Documentation:
  Perform a simple BatchX `hello world` execution.

  # Context
  This is one of BatchX [tutorial images](https://docs.batchx.io/documentation/tutorials), intended for first time users who want to run their very first job in BatchX or those who are in the process of learning how to implement their own BatchX image.

  # File Formats
  ### Inputs
  To run this image the user has to provide his name as a `String` for the `yourName` input.

  ### Outputs
  Once the image runs successfully it will return an output file `responseFile` with the following content:

  Hello <your_name>. Welcome to BatchX!

  # Example

  ### Submit job

  bx submit batchx@tutorial/hello-world:1.0.3 '{"yourName":"Rocky Balboa"}'


  # Links
  - **BatchX Tutorials:** https://docs.batchx.io/documentation/tutorials

--------------------------------------------------------------------------------
Input:
  {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "yourName": {
        "type": "string",
        "required": true,
        "description": "Your name."
      }
    }
  }
--------------------------------------------------------------------------------
Output:
  {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "responseFile": {
        "required": true,
        "type": "string",
        "format": "file",
        "description": "Hello World response file."
      }
    }
  }

Run a job​

You can now use bx run to run the image in the BatchX infrastructure.

Let's first try with an empty input to see what happens:

$ bx run batchx@tutorial/hello-world:1.0.3 '{}'
[batchx] [2020/04/28 18:50:42] Submitting job...
[batchx] [2020/04/28 18:50:42] Error INVALID_ARGUMENT: Input validation failed: [object has missing required properties (["yourName"])]

As you can see the input validation is failing, because the yourName field is marked as required in the input schema of the image manifest.

Let's run again with a proper input message:

$ bx run batchx@tutorial/hello-world:1.0.3 '{"yourName":"Michael Jordan"}'

Logs should start showing in your screen as soon as the job is submitted. These logs provide information of the job id, transitions between execution states and logs generated by the running container.

$ bx run tutorial/hello-world:1.0.0 '{"yourName":"Michael Jordan"}'
[batchx] [INFO] [2020/03/09 17:37:16] Submitting job...
[batchx] [INFO] [2020/03/09 17:37:18] Job submitted with id 1
[batchx] [INFO] [2020/03/09 17:37:18] Attaching to job 1
[batchx] [INFO] [2020/03/09 17:37:19] Job status: SUBMITTED
[batchx] [INFO] [2020/03/09 17:41:18] Job status: STARTING
[batchx] [INFO] [2020/03/09 17:41:18] Job status: DOWNLOADING_INPUT
[batchx] [INFO] [2020/03/09 17:41:19] Job status: RUNNING
[tutorial/hello-world:1.0.0] [2020/03/09 17:41:22] Environment:
[tutorial/hello-world:1.0.0] [2020/03/09 17:41:22] environ({'HOSTNAME': 'batchx-container', 'PYTHON_PIP_VERSION': '20.0.2', 'HOME': '/root', 'GPG_KEY': 'E3FF2839C048B25C084DEBE9B26995E310250568', 'PYTHON_GET_PIP_URL': 'https://github.com/pypa/get-pip/raw/d59197a3c169cef378a22428a3fa99d33e080a5d/get-pip.py', 'PATH': '/usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin', 'BX_MEMORY': '1000', 'LANG': 'C.UTF-8', 'BX_GPUS': '0', 'PYTHON_VERSION': '3.8.1', 'BX_VCPUS': '1', 'PWD': '/batchx', 'PYTHON_GET_PIP_SHA256': '421ac1d44c0cf9730a088e337867d974b91bdce4ea2636099275071878cc189e'})
[batchx] [INFO] [2020/03/09 17:41:30] Job status: UPLOADING_OUTPUT
[batchx] [INFO] [2020/03/09 17:41:31] Job status: SUCCEEDED
{"responseFile":"bx://jobs/1/output/response/response.txt"}

info

If the compute environment had no previous activity the job might take a few minutes to start.

Inspect results​

Each job generates a folder under /jobs in your BatchX file-system, which is persisted in the BatchX cloud. You can inspect its contents by running the bx treecommand:

$ bx tree -i jobs/1
1
├── [32 B] image.txt
├── input
│   ├── [29 B] input.json
│   └── [29 B] original-input.json
└── output
    ├── [60 B] output.json
    └── response
        └── [41 B] response.txt

The image we are using for this example writes its output to a file named response.txt. The last line of the log shows where this output was created. Use bx cat to inspect the contents of this file:

$ bx cat jobs/1/output/response/response.txt
Hello Michael Jordan. Welcome to BatchX!
info

Congratulations! You have successfully configured your BatchX account and executed a job.

Next steps​

Now, you can dive deeper into the documentation:

Images

or try more advanced tutorials:

Tutorials