Since OpenLMIS system runs in dockerized environment, using services that are already compiled, and published as images, there's no live access to source code of a service. This means we can't simply modify and debug a service in this environment. However, it is possible to attach service that is running locally to a running OpenLMIS system. This means we can run a service (or several services) locally in development mode (with ability to quickly rebuild and debug), and have OpenLMIS redirect incoming requests to this service.

There are few short steps to take in order to debug a service (in this case, we'll debug requisition):

1. In openlmis-ref-distro's compose file, comment requisition service section (so the reference distribution will start without it).
2. Add network_mode: "host" parameter to nginx container in openlmis-ref-distro compose file.
OR add to requisition service docker-compose.yml fle
networks:
default:
external:
name: openlmis-ref-distro_default

3. Run openlmis-ref-distro as normal.
4. Enter openlmis-requisition's folder, and edit your settings.env file to have it's BASE_URL and CONSUL_HOST values the same as in openlmis-ref-distro.
5. You may need to remove log and db services plus links to them from the docker.compose.yml of the service you want to debug, so it only starts the image with actual OpenLMIS service (in this case openlmis-requisition)
6. Run service as usual with docker-compose run --service-ports requisition.
7. Run npm install.
8. Run gradle consulRegistration.
9. Run gradle bootRun --debug-jvm
10. Attach debugger in your IDE.

* You may possibly approach some problems with installing npm dependencies - if running step 7 or step 8 causes an error (such as Cannot find module 'command-line-args'), please copy all references from consul/package.json to package.json at root (or go to the consul folder) and re-run npm install.