Skip to main content

Debugging Artemis in Docker

Sometimes it is useful to debug Artemis while it is running in a Docker container as some bugs can be most easily reproduced in a Docker setup (e.g., for multi-node setups).

Follow these steps to set up debugging:

Adjust the Docker Setup​

Adjust the docker setup to start the JVM with the correct arguments and to expose a debug port.

This can be done by adding the following lines to the relevant docker compose file and setting the debug port for each artemis service:

environment:
  - JAVA_TOOL_OPTIONS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:<debug-port>
ports:
  - "<debug-port>:<host-port>"

This will start the JVM with the Java Debug Wire Protocol (JDWP) agent, allowing you to connect a debugger to port <host-port>.

Use Your Own PR Image (Optional)​

If you want to debug your own PR, replace the image name with your own PR image

ghcr.io/ls1intum/artemis:pr-<pr-number>

Configure IntelliJ Remote Debugging​

Use the Remote Java Debugging for Docker run configuration:

  • This configuration is set up to connect to port 5005 as the default debug port.
  • If you used another port for the debugger port on the host, you need to change the port in the run configuration accordingly.
  • You can find the run configuration in the Run/Debug Configurations dialog in IntelliJ under Remote JVM Debug -> Remote Java Debugging for Docker.
  • For each Artemis node you want to debug, you need to create a separate run configuration with the correct port.

Start the Docker Compose File​

Start the relevant docker compose file with:

docker compose -f <docker compose file name> up -d

Handle Liquibase Errors (If Necessary)​

If the server fails to start with Liquibase errors, you can run the following command to reset the database:

  1. Stop the Artemis server, because PostgreSQL refuses to drop a database while a session is connected to it. Keep the PostgreSQL container running:

    docker stop artemis-app

  2. Drop the database and create it again. The PostgreSQL connection URL of Artemis does not create the database, and restarting the PostgreSQL container with its existing data volume does not run the initialization again:

    docker exec -i artemis-postgres psql -U Artemis -d postgres -c 'DROP DATABASE "Artemis";'
    docker exec -i artemis-postgres psql -U Artemis -d postgres -c 'CREATE DATABASE "Artemis" OWNER "Artemis";'

  3. Start the Artemis server again, for example with docker start artemis-app, or with the same command as under Start the Docker Compose File. Liquibase then creates the schema from scratch.

For a MySQL setup (deprecated, removed in Artemis 11), stop the server and use docker exec -i artemis-mysql mysql -u root -p'' -e "DROP DATABASE Artemis;" instead. The MySQL connection URL contains createDatabaseIfNotExist=true, so the next start of the server creates the database again.

Start the Remote Debugger​

Start the Remote JVM Debug configuration in IntelliJ.

Set Breakpoints​

Set breakpoints in the code you want to debug and start debugging!

Search documentation