Installation
Install the Bacalhau CLI
In this tutorial, you'll learn how to install and run a job with the Bacalhau client using the Bacalhau CLI or Docker.
Step 1 - Install the Bacalhau Client
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.
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.
Step 1.1 - Install the Bacalhau 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
:
Step 1.2 - Verify the Installation
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
.
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.
Step 2 - Submit a Hello World job
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:
To run the job, you will need to connect to a public demo network or set up your own private network. In the following example, we will use the public demo network by using the --configuration
flag.
We will use the command to submit a Hello World job that runs an echo program within an Alpine container.
Let's take a look at the results of the command execution in the terminal:
After the above command is run, the job is submitted to the selected network, which processes the job and Bacalhau prints out the related job id:
The job_id
above is shown in its full form. For convenience, you can use the shortened version, in this case: j-de72aeff
.
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.
Step 3 - Checking the State of your Jobs
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.
Step 3.1 - Job information:
You can find out more information about your job by using bacalhau job describe
.
Let's take a look at the results of the command execution in the terminal:
This outputs all information about the job, including stdout, stderr, where the job was scheduled, and so on.
Step 3.2 - Job download:
You can download your job results directly by using bacalhau job get
.
Depending on selected publisher, this may result in:
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.
After the download has finished you should see the following contents in the results directory.
Step 4 - Viewing your Job Output
That should print out the string helloWorld
.
Step 5 - Where to go next?
Here are few resources that provide a deeper dive into running jobs with Bacalhau:
How Bacalhau works, Create your Private Network, Examples & Use Cases
Support
If you have questions or need support or guidance, please reach out to the Bacalhau team via Slack (#general channel).
Last updated