ICD-API in a Container
You may find generic information on deploying the ICD-API locally at the ICD-API Local Deployment Page
Installing the ICD-API as a Docker container
You may install our docker image in to any computer that has Docker (You could use Linux, Mac, Windows 10/11 or a recent Windows Server, etc.)
First you need to install docker if you don't have it already. This depends on the operating therefore we are not providing the details of this. However, it is a fairly a straight forward process.
Once you have docker, you need to run a container with our image.
docker run command creates the container from the image we provide. You may use some parameters in the docker run command to configure the container that you are creating. The command will load the container image and ICD-11 therefore it may take some time if you have a slow Internet connection. Once the container is created you will not need Internet connection to run the API locally.
Basic configuration
docker run -p 80:80 -e acceptLicense=true -e saveAnalytics=true whoicd/icd-api
-e acceptLicense=true is a required parameter which means you agree with the license agreement
-e saveAnalytics=true If you set this option to true, the container that is deployed can send data to WHO on the searches made in order to improve search capability of ICD-11 tools. The data that is sent does not contain any ids or IP addresses.
If you don't provide this parameter or set it to false the container will not collect or send any data.
Using different language versions
By default the container loads the latest release of the ICD-11 in English 2024-01_en. However, you could use the include parameter to use a different release or a language version.
docker run -p 80:80 -e include=2024-01_es -e acceptLicense=true -e saveAnalytics=true whoicd/icd-api
In the example above, we load the Spanish version.
docker run -p 80:80 -e include=2024-01_tr -e acceptLicense=true -e saveAnalytics=true whoicd/icd-api
In the example above, we load the Turkish version.
One could load multiple language versions as well:
docker run -p 80:80 -e include=2024-01_ar-en -e acceptLicense=true -e saveAnalytics=true whoicd/icd-api
In the example above, we load the English and Arabic versions.
Using an older release
It's possible to load an older release of ICD-11 in the container using the include parameter
docker run -p 80:80 -e include=2023-01_en -e acceptLicense=true -e saveAnalytics=true whoicd/icd-api
Available versions and languages of ICD-11 are listed at the supported classifications. ICD-10 is not supported in the containers at the moment.
It is recommended that you load only the languages that you need because each version/language increase the amount of resources your container will require.
Using a different port
You may configure your container to serve the API from a different port than 80.
docker run -p 8000:80 -e acceptLicense=true -e saveAnalytics=true whoicd/icd-api
Here, the container is configured to run from the port 8000
Once the container is ready you'll see this screen
____________________________________________________________________________
ooooo .oooooo. oooooooooo. .o. ooooooooo. ooooo
888 d8P Y8b 888 Y8b .888. 888 Y88. 888
888 888 888 888 .8 888. 888 .d88 888
888 888 888 888 .8 888. 888ooo88P 888
888 888 888 888 88888 .88ooo8888. 888 888
888 88b ooo 888 d88 .8 888. 888 888
o888o Y8bood8P o888bood8P o88o o8888o o888o o888o
https://icd.who.int/icdapi
____________________________________________________________________________
Saving Analytics is ON
Starting ICD-API
ICD-11 Container is Running!
You may close the shell window or Ctrl-C to return to shell (container will continue to run)
At this point your container with the ICD-API is up and running. You may check it by opening the swagger endpoint /swagger/index.html (if your container is deployed at the localhost, this would be http://localhost/swagger/index.html)
Coding Tool and Browser are included
ICD-11 Coding Tool and ICD-11 Browser applications are included as a part of the ICD-API container. Coding Tool is available at the URL /ct and
the ICD-11 Browser is available at /browse
If your container is deployed at the localhost, this would be http://localhost/ct and http://localhost/browse
So, you could check if your container is correctly running by loading the Coding Tool within your container at the /ct or the ICD-11 Browser at the /browse.
More Docker Information
docker run command creates a container in your system and runs it. Once this is done you could start and stop your container without providing any of the configuration parameters mentioned above by using the docker stop and docker start commands. For more information please see Docker documentation.
Internet access and proxy server configuration
The container needs to have Internet access during the docker run command when the container is being created and the first time it runs. After that, the container can work without access to the Internet.
If you are accessing the Internet behind a proxy server that information needs to passed to the container so that it can access the Internet. This can be done by adding an additional parameter to the docker run command
For example, if you are behind a proxy server http://proxy.myserver.com:8080, you need to add
-e https_proxy=http://proxy.myserver.com:8080 to the docker run command
docker run -p 80:80 -e acceptLicense=true -e saveAnalytics=true -e https_proxy=http://proxy.myserver.com:8080 whoicd/icd-api
Updating the Container
You may update your Docker container when there is a new docker image. We generally update our docker images when there is a new version of the classification.
Updating the image
docker pull who-icd/icd-api command will update the icd-api docker image that you have in your computer. If you already have the latest image, this command will result with the message Image is up to date for whoicd/icd-api:latest In that case you don't need to do anything as you are already using the latest version.
docker pull command updates the image but this does not update the existing containers running an earlier version of the image. To do that, you need to remove the existing container and create a new one.
Removing existing container
docker ps command will give the running containers.
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
6094414a756c whoicd/icd-api
In this example the system is running whoicd/icd-api image in the container 6094414a756c
docker rm 6094414a756c -f will remove this container.
Once the existing container is removed, you could run the docker run command as explained in the installation part of this document to create a new container. Since the docker image is already updated, the newly created containers will be using the new version.
Enabling DORIS
DORIS (Underlying cause of death detection) functionality is in pre-release state. For this reason it is not enabled by default.
You may enable the DORIS endpoints using the enableDoris=true parameter
docker run -p 80:80 -e enableDoris=true -e acceptLicense=true -e saveAnalytics=true whoicd/icd-api
For more information about DORIS support see the release notes.