Running CRaC in a Container (Docker)

Table of Contents

Creating a Docker Image
- Starting an Application in a Docker Container
  - Using the CRIU Engine
Creating the Checkpoint
Creating a Docker Image with Checkpoint
Run the Docker Container From the Checkpoint

Need help?

Schedule a consultation with an Azul performance expert.

The following instructions add container-specific information to Running an Application With CRaC on Linux.

Creating a Docker Image

You need an application with the CRaC integration in a runnable JAR file.
Check which Zulu Docker Image version you want to use on Docker Hub.

Create a Dockerfile, based on the following minimum file (using Zulu 21 in this example):

 FROM azul/zulu-openjdk:21-jdk-crac-latest
COPY build/libs/my_app.jar /opt/app/my_app.jar

Build the Docker image with:
```
 docker build -t my_app_on_crac .
```

Starting an Application in a Docker Container

Run a Docker container with:

 # Run a new container interactively (-i) with a terminal (-t)
docker run -it \
  # Automatically remove the container when it exits (cleanup)
  --rm \
  # Name of the container for easy reference
  --name my_app_on_crac \
  # Mount a volume
  -v $PWD/crac-files:/opt/crac-files \
  # Docker image name to us
  my_app_on_crac \
  # Start the Java application with
  #  - The location for the CRaC checkpoint
  #  - The Warp engine (recommended)
  java -XX:CRaCCheckpointTo=/opt/crac-files -XX:CRaCEngine=warp -jar /opt/app/my_app.jar

Leave the shell window open and the application running.

Using the CRIU Engine

You can use the CRIU engine in a Docker, but this requires additional capabilities and is more challenging to configure. You need to add these arguments to your docker command:

--cap-add=CHECKPOINT_RESTORE: Grant the Linux capability to create and restore checkpoints.
--cap-add=SYS_PTRACE: Grant the Linux capability to trace processes.

If you want to avoid possible PID conflicts on restore, check Resolving PID Conflicts.

Creating the Checkpoint

Open another shell window.
In this window run with jcmd 0 which applies to all JVMs.:
```
 docker exec my_app_on_crac jcmd 0 JDK.checkpoint
```
If everything is ok, you see that in the first shell window the checkpoint was created and your application was closed.

Creating a Docker Image with Checkpoint

Create a Dockerfile with the checkpoint:

 FROM my_app_on_crac
COPY crac-files /opt/crac-files

Build the Docker image with

 docker build -t my_app_on_crac_restore .

Run the Docker Container From the Checkpoint

Run:

 docker run -it --rm my_app_on_crac_restore java \
    -XX:CRaCRestoreFrom=/opt/crac-files \
    -XX:CRaCEngine=warp

Your application now starts much faster from the saved checkpoint.

Note	You can run the Docker container also on macOS or Windows, as long as the machine you are running it on has a x64 cpu architecture (Intel/AMD).