diff --git a/README.md b/README.md index 463e344..4d44cfe 100644 --- a/README.md +++ b/README.md @@ -163,6 +163,7 @@ RunCVM features: - [Advanced usage](#advanced-usage) - [Developing](#developing) - [Building](#building) +- [Testing](#testing) - [Contributing](#contributing) - [Support](#support) - [Uninstallation](#uninstallation) @@ -636,6 +637,59 @@ The build script creates a Docker image named `newsnowlabs/runcvm:latest`. Now follow the main [installation instructions](#installation) to install your built RunCVM from the Docker image. +## Testing + +Test RunCVM using nested RunCVM. You can do this using a Docker image capable of installing RunCVM, or an image built with a version of RunCVM preinstalled. + +Build a suitable image as follows: + +```sh +cat <>/etc/modules && \ + useradd --create-home --shell /bin/bash --groups sudo,docker runcvm && \ + echo runcvm:runcvm | chpasswd && \ + echo 'runcvm ALL=(ALL) NOPASSWD: ALL' >/etc/sudoers.d/runcvm + +WORKDIR /home/runcvm +ENTRYPOINT ["/lib/systemd/systemd"] +VOLUME /disks + +# Mount formatted backing file at /var/lib/docker for speed and overlay2 support +ENV RUNCVM_DISKS='/disks/docker,/var/lib/docker,ext4,2G' + +# # Uncomment this block to preinstall RunCVM from the specified image +# +# COPY --from=newsnowlabs/runcvm:latest /opt /opt/ +# RUN rm -f /etc/init.d/docker && \ +# bash /opt/runcvm/scripts/runcvm-install-runtime.sh --no-dockerd +EOF +``` + +(Uncomment the final block to build an image with RunCVM preinstalled, or leave the block commented to test RunCVM installation). + +To launch, run: + +```sh +docker run -d --runtime=runcvm -m 2g --name=ubuntu-docker-runcvm ubuntu-docker-runcvm +``` + +> Optionally modify this `docker run` command by: +> - adding `--rm` - to automatically remove the container after systemd shutdown +> - removing `-d` and adding `--env=RUNCVM_KERNEL_DEBUG=1` - to see kernel and systemd boot logs +> - removing `-d` and adding `-it` - to provide a console + +Then `docker exec -it -u runcvm ubuntu-docker-runcvm bash` to obtain a command prompt and perform testing. + +Run `docker rm -fv ubuntu-docker-runcvm` to clean up after testing. + ## Support **Support launching images:** If you encounter any Docker image that launches in a standard container runtime that does not launch in RunCVM, or launches but with unexpected behaviour, please [raise an issue](https://github.com/newsnowlabs/runcvm/issues) titled _Launch failure for image ``_ or _Unexpected behaviour for image ``_ and include log excerpts and an explanation of the failure, or expected and unexpected behaviour.