Setting up with Docker on Linux

Get Source Code

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

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

OpenCIS Core

Go to the root directory of opencis and get the OpenCIS Core source by:

git submodule update --init --progress opencis-core

OpenCIS QEMU

Go to the root directory of opencis and get the OpenCIS QEMU source by:

git submodule update --init --recursive --progress opencis-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 opencis, run:

note

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

docker build -f opencis-core/docker/Dockerfile-dev -t opencis.io/opencis-core .

QEMU

Stay in the root directory of opencis and run:

docker build -f opencis-qemu/docker/Dockerfile-dev -t opencis.io/opencis-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: opencis-net.

docker network create opencis-net

Start Containers

Stay in the root directory of opencis and run:

docker run -d \
  -v $PWD/opencis-core:/opencis-core \
  --network opencis-net \
  --name opencis-core \
  opencis.io/opencis-core

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

Next, we will start a container for QEMU.

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

This starts a container named opencis-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 opencis-core and opencis-qemu are "Up" (e.g. "Up 25 seconds").

Access opencis-core Container

docker exec -it opencis-core /bin/bash

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

Access opencis-qemu Container

Open another terminal and run:

docker exec -it opencis-qemu /bin/bash

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

We now need to build QEMU. Inside of /opencis-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 opencis-core", it is /opencis-core in opencis-core container. "opencis-qemu directory" is /opencis-qemu in opencis-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