Setting up with Docker on Linux

Get Source Code

git clone https://github.com/opencxl/opencxl.git

This top-level source contains multiple git submodules. We will work through them one at a time.

OpenCXL Core

Go to the root directory of opencxl and get the OpenCXL Core source by:

git submodule update --init --progress opencxl-core

OpenCXL QEMU

Go to the root directory of opencxl and get the OpenCXL QEMU source by:

git submodule update --init --recursive --progress opencxl-qemu

Build Docker Images

We will build two docker images for each component (Python and QEMU). These images will provide a dev/run environment that can be used in lieu of the native Ubuntu environment. In the following Run section, you will run the commands inside of this environment.

Core

From the root directory of opencxl, run:

note

Don't forget the dot ('.') at the end.

docker build -f opencxl-core/docker/Dockerfile-dev -t opencxl.org/opencxl-core .

QEMU

Stay in the root directory of opencxl and run:

docker build -f opencxl-qemu/docker/Dockerfile-dev -t opencxl.org/opencxl-qemu .

Container Setup

We will now create two containers based on the two images we have built and connect them in a Docker managed virtualized network. The following diagram illustrates the intended setup. This is only a preview. No need to fret if something doesn't make sense.

Create a Docker Network

Docker containers can connect to one another in a Docker managed virtual network. They can find each other by the container's name or by its IP address.

We will name our network: opencxl-net.

docker network create opencxl-net

Start Containers

Stay in the root directory of opencxl and run:

docker run -d \
  -v $PWD/opencxl-core:/opencxl-core \
  --network opencxl-net \
  --name opencxl-core \
  opencxl.org/opencxl-core

This starts a container named opencxl-core which is for Python components.

Next, we will start a container for QEMU.

docker run -d \
  -v $PWD/opencxl-qemu:/opencxl-qemu \
  --device=/dev/kvm:/dev/kvm \
  --device=/dev/net/tun:/dev/net/tun \
  --network opencxl-net \
  --name opencxl-qemu \
  opencxl.org/opencxl-qemu

This starts a container named opencxl-qemu.

To review, the following diagram illustrates what we have created so far.

Access Containers

Similar to logging into a remote machine via SSH/telnet, one can get terminal access to a running container by:

docker exec -it <name of the container> /bin/bash

First, confirm that the two containers we started are up.

docker ps

Confirm that both opencxl-core and opencxl-qemu are "Up" (e.g. "Up 25 seconds").

Access opencxl-core Container

docker exec -it opencxl-core /bin/bash

You will be directed to /opencxl-core. This is a mapped directory of the root directory of opencxl-core on the host machine. Hence, the changes you make in the host machine's opencxl-core directory will be automatically reflected on this directory in the container (and vice versa).

Access opencxl-qemu Container

Open another terminal and run:

docker exec -it opencxl-qemu /bin/bash

You will be in directed to /opencxl-qemu, a mapped directory of opencxl-qemu on the host machine.

We now need to build QEMU. Inside of /opencxl-qemu directory, create build directory:

mkdir build && cd build

Once in build, configure and build QEMU by:

../configure --target-list=x86_64-softmmu --enable-debug --enable-slirp --with-git-submodules=ignore && make -j$(nproc)

Finally, we need to download the guest OS images and the credential file to build:

wget https://download.fedoraproject.org/pub/fedora/linux/releases/39/Cloud/x86_64/images/Fedora-Cloud-Base-39-1.5.x86_64.qcow2
wget https://eeum.s3.us-west-1.amazonaws.com/public/qemu-images/fedora_39.qcow2
wget https://eeum.s3.us-west-1.amazonaws.com/public/qemu-images/seed.qcow2

note

• Once again, in the next section, you will be running the commands inside of these containers. When the instruction directs you to "the root directory opencxl-core", it is /opencxl-core in opencxl-core container. "opencxl-qemu directory" is /opencxl-qemu in opencxl-qemu container.

• The above setup instructions are intended for Docker beginners. Advanced Docker users can examine Dockerfile-svc in the respective docker directories to see how they can be incorporated into an iterative build and run process.

Continue to Run Instructions