Running With Docker on Your Machine

1. Obtain Catena source code

Catena is distributed via Git. Instructions for installing Git can be found here.

To gain access to the Catena Source, please contact us to obtain a license. Once you have access, clone Catena to your machine.

git clone git@github.com:CatenaTools/catena-tools-core.git

2. Install WSL

There are two options for running with Docker: with Docker Desktop, or by using Docker Engine directly. Both options will require you to install WSL on your machine.

Full instructions for installing WSL can be found in these official Microsoft docs, but we've included a condensed version here.

1. Open PowerShell in administrator mode by right-clicking and selecting “Run as administrator”
2. Install WSL (We recommend using the Ubuntu 24.04 LTS distro.)

wsl --install -d Ubuntu-24.04

3. Restart your machine

3. Install Docker

Using Docker Desktop

Docker Desktop is the easiest way to install Docker onto a Windows machine, though it requires a paid license for commercial use. If you prefer to register for a license, follow the instructions below. Otherwise, skip to Using Docker Engine Directly.

1. Download Docker Desktop
2. Begin installation
   • Ensure you select Use WSL 2 instead of Hyper-V
3. Once complete, start Docker Desktop
4. From Powershell, check that Docker is working correctly:

docker run hello-world
# Expected output should include:
# Hello from Docker!
# This message shows that your installation appears to be working correctly.

docker compose version
# Expected output should include something similar to:
# Docker Compose version v2.32.1

5. Proceed To Run Catena

Using Docker Engine Directly

1. Open the Ubuntu-24.04 application, or whichever distro you chose when installing WSL
2. Install Docker Engine using the apt repository using these instructions
3. Install Docker Compose using these instructions
4. If you have not already, verify that Docker is working correctly

docker run hello-world
# Expected output should include:
# Hello from Docker!
# This message shows that your installation appears to be working correctly.

docker compose version
# Expected output should include something similar to:
# Docker Compose version v2.32.1

sudo apt-get remove docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

5. Add your user to the docker group

sudo usermod -aG docker $USER

6. Tell Docker Engine you are not using Docker Desktop by replacing the automatically defined credential helper with empty JSON in Docker's config.

echo '{}' | sudo tee ~/.docker/config.json

7. Proceed To Run Catena

4. Run Catena

1. Depending on how you installed Docker, use the corresponding command prompt to navigate to the root directory of the Catena Project:
   • Docker Desktop: Powershell
   • Docker Engine: WSL

     To navigate to a drive from WSL, such as your C:\ drive, you will need to cd /mnt/c/<YOUR_INSTALLATION_DIRECTORY>

2. Use Docker Compose to run the project (this may take a while)

docker compose up

3. Check that Catena is running either by sending a request from this page using the provided interactive API, or by using cURL.

Send Request From This Page

Use cURL

curl -i -X GET \
  http://localhost:5000/api/v1/node_inspection/is_healthy

{
  "isHealthy": true
}