icon |
---|
square-down |
In this tutorial, you'll learn how to install and run a job with the Bacalhau client using the Bacalhau CLI or Docker.
The Bacalhau client is a command-line interface (CLI) that allows you to submit jobs to the Bacalhau. The client is available for Linux, macOS, and Windows. You can also run the Bacalhau client in a Docker container.
{% hint style="info" %} By default, you will submit to the Bacalhau public network, but the same CLI can be configured to submit to a private Bacalhau network. For more information, please read Running Bacalhau on a Private Network. {% endhint %}
{% tabs %}
{% tab title="Linux/macOS (CLI)" %}
You can install or update the Bacalhau CLI by running the commands in a terminal. You may need sudo mode or root password to install the local Bacalhau binary to /usr/local/bin
:
curl -sL https://get.bacalhau.org/install.sh | bash
{% endtab %}
{% tab title="Windows (CLI)" %}
Windows users can download the latest release tarball from Github and extract bacalhau.exe
to any location available in the PATH environment variable.
{% endtab %}
{% tab title="Docker" %}
docker image rm -f ghcr.io/bacalhau-project/bacalhau:latest # Remove old image if it exists
docker pull ghcr.io/bacalhau-project/bacalhau:latest
To run a specific version of Bacalhau using Docker, use the command docker run -it ghcr.io/bacalhau-project/bacalhau:v1.0.3
, where v1.0.3
is the version you want to run; note that the latest
tag will not re-download the image if you have an older version. For more information on running the Docker image, check out the Bacalhau docker image example.
{% endtab %}
{% endtabs %}
To verify installation and check the version of the client and server, use the version
command. To run a Bacalhau client command with Docker, prefix it with docker run ghcr.io/bacalhau-project/bacalhau:latest
.
{% tabs %} {% tab title="Linux/macOS/Windows (CLI)" %}
bacalhau version
{% endtab %}
{% tab title="Docker" %}
docker run -it ghcr.io/bacalhau-project/bacalhau:latest version
{% endtab %} {% endtabs %}
If you're wondering which server is being used, the Bacalhau Project has a demo network that's shared with the community. This network allows you to familiarize with Bacalhau's capabilities and launch jobs from your computer without maintaining a compute cluster on your own.
To submit a job in Bacalhau, we will use the bacalhau docker run
command. The command runs a job using the Docker executor on the node. Let's take a quick look at its syntax:
bacalhau docker run [FLAGS] IMAGE[:TAG] [COMMAND]
{% tabs %} {% tab title="CLI" %}
bacalhau docker run ubuntu echo Hello World
We will use the command to submit a Hello World job that runs an echo program within an Ubuntu container.
Let's take a look at the results of the command execution in the terminal:
Job successfully submitted. Job ID: f8e7789d-8e76-4e6c-8e71-436e2d76c72e
Checking job status... (Enter Ctrl+C to exit at any time, your job will continue running):
Communicating with the network ................ done ✅ 0.2s
Creating job for submission ................ done ✅ 0.7s
Job in progress ................ done ✅ 2.1s
To download the results, execute:
bacalhau job get f8e7789d-8e76-4e6c-8e71-436e2d76c72e
To get more details about the run, execute:
bacalhau job describe f8e7789d-8e76-4e6c-8e71-436e2d76c72e
After the above command is run, the job is submitted to the public network, which processes the job and Bacalhau prints out the related job id:
Job successfully submitted. Job ID: 9d20bbad-c3fc-48f8-907b-1da61c927fbd
Checking job status...
The job_id
above is shown in its full form. For convenience, you can use the shortened version, in this case: 9d20bbad
.
{% hint style="info" %} While this command is designed to resemble Docker's run command which you may be familiar with, Bacalhau introduces a whole new set of flags to support its computing model. {% endhint %} {% endtab %}
{% tab title="Docker" %}
docker run -t ghcr.io/bacalhau-project/bacalhau:latest \
docker run \
--id-only \
--wait \
ubuntu:latest -- \
sh -c 'uname -a && echo "Hello from Docker Bacalhau!"'
Let's take a look at the results of the command execution in the terminal:
14:02:25.992 | INF pkg/repo/fs.go:81 > Initializing repo at '/root/.bacalhau' for environment 'production'
19b105c9-4cb5-43bd-a12f-d715d738addd
{% endtab %} {% endtabs %}
After having deployed the job, we now can use the CLI for the interaction with the network. The jobs were sent to the public demo network, where it was processed and we can call the following functions. The job_id
will differ for every submission.
You can check the status of the job using bacalhau job list
command adding the --id-filter
flag and specifying your job id.
bacalhau job list --id-filter 9d20bbad
Let's take a look at the results of the command execution in the terminal:
CREATED ID JOB STATE PUBLISHED
15:24:31 0ed7617d Type:"docker",Params:"map[Entrypoint:<ni Completed
l> EnvironmentVariables:[] Image:ubuntu:
latest Parameters:[sh -c uname -a && ech
o "Hello from Docker Bacalhau!"] Working
Directory:]"
When it says Completed
, that means the job is done, and we can get the results.
{% hint style="info" %} For a comprehensive list of flags you can pass to the list command check out the related CLI Reference page {% endhint %}
You can find out more information about your job by using bacalhau job describe
.
bacalhau job describe 9d20bbad
Let's take a look at the results of the command execution in the terminal:
Job:
APIVersion: V1beta2
Metadata:
ClientID: 0ff57b2521334a92e9ddab4b2f8202c887b1eaa35d2aa945ab0e247d3bc0aa88
CreatedAt: "2023-12-21T15:24:31.750306239Z"
ID: 0ed7617d-d5ff-40f7-8411-89830b3f3058
Requester:
RequesterNodeID: QmbxGSsM6saCTyKkiWSxhJCt6Fgj7M9cns1vzYtfDbB5Ws
RequesterPublicKey: CAASpgIwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDEHTUAD1JzO0130W9vsaDGhU0PVgpcNjG3fYlE0sJ1BiBWENFuP4jx3Q9alcjNGhdRFdju0Mb/fidTOtJcPhxTdb+H6JxFP6HsADGes9jU4ylBU2SL2vfdb0KXzKdXjNHGGf4BuCGTcH07Oqxp209diK/cT7takL2fLjcgs1tM+6PzlfGzFqCPxvh9Sa0ek34mdmHjcp1XH8yjF1OKOuHvD+pYphqvOBL/2LEN+EBC4fz/QUnhUajCmKYO83MJcNUXSGxb4AN6K3DpVV+cJph7fj9ADdP7i996o2S4Gkz8W4Wpt/jICaPpkUjmyU3Jgcw7MHkZaYEzWxnnO2J936+pAgMBAAE=
Spec:
...
This outputs all information about the job, including stdout, stderr, where the job was scheduled, and so on.
You can download your job results directly by using bacalhau job get
.
bacalhau job get 9d20bbad
This results in
Fetching results of job '0ed7617d'...
Results for job '0ed7617d' have been written to...
/Users/test/job-0ed7617d
In the command below, we created a directory called myfolder
and download our job output to be stored in that directory.
Fetching results of job '0ed7617d'...
Results for job '0ed7617d' have been written to...
/myfolder
{% hint style="info" %}
While executing this command, you may encounter warnings regarding receive and send buffer sizes: failed to sufficiently increase receive buffer size
. These warnings can arise due to limitations in the UDP buffer used by Bacalhau to process tasks. Additional information can be found in https://github.com/quic-go/quic-go/wiki/UDP-Buffer-Sizes.
{% endhint %}
After the download has finished you should see the following contents in the results directory.
job-0ed7617d
├── exitCode
├── outputs
├── stderr
└── stdout
cat job-9d20bbad/stdout
That should print out the string Hello World
.
Hello world
With that, you have just successfully run a job on Bacalhau! 🐟
Here are few resources that provide a deeper dive into running jobs with Bacalhau:
How Bacalhau works, Create your Private Network, Examples & Use Cases
If you have questions or need support or guidance, please reach out to the Bacalhau team via Slack (#general channel).