Docker Compose - department-of-veterans-affairs/abd-vro GitHub Wiki

There are various other Docker setups depending on your needs, this page provides some guidance and typical setups to use during development. It also provides additional details for you to customize your own Docker setup, depending on your current development focus.

Docker Compose is used to define multi-container Docker setups for local development and integration tests. It sets up a Docker network, so that containers can readily connect using obvious hostnames rather than localhost. It also sets up shared volumes to simulate LHDI deployment environments.

Docker setups:

• Platform Base setup (docker-compose.yml): includes Postgres, Redis, RabbitMQ, API Gateway. This creates Docker volumes and a network required by other setups.
• App setup (app/docker-compose.yml): includes the Java-based VRO App and platform (domain-independent) microservices
• Mocks setup (mocks/docker-compose.yml): defines containers that act as substitutes for External APIs and services; only used only for development and integration testing
• Domain setups (domain-*/docker-compose.yml): each defines containers for their respective domain

For configurability, a docker-compose.yml file can use compose profiles to run a subset of defined containers. Examine the file to see what profiles are available for each Docker setup. The environment variable COMPOSE_PROFILES determines which containers are started by docker-compose (or docker compose). This allows developers to start only the containers they need for their current work.

For even further customization, create a local docker-compose.override.yml (docs) but do commit it to git.

The following instructions, assume the Docker container images have been built: ./gradlew docker

The Gradle tasks to start up and shut down the Docker setups are dockerComposeUp and dockerComposeDown. Alternatively, the equivalent docker compose command can be used instead.

Platform Base

• Start up: ./gradlew :dockerComposeUp (Note the :, which will run the dockerComposeUp task in only the root Gradle project).
  • Equivalent to docker compose up -d
  • Check that all containers are healthy: docker ps -a
  • Manually test: visit the RabbitMQ Management UI at http://localhost:15672/
• Shut down: ./gradlew :dockerComposeDown or ./gradlew :dockerComposeDown :dockerPruneVolume
  • Equivalent to docker compose down or docker compose down --volume (respectively)

Platform Base + API-Gateway

The Platform Base defines an API Gateway container but it is not needed for typical development, so it is not started by default. To start it, set COMPOSE_PROFILES:

• Start up: COMPOSE_PROFILES="gateway" ./gradlew :dockerComposeUp
  • Note: Setting COMPOSE_PROFILES on the same command line as running ./gradlew will set the variable to the specified value for only that Gradle execution. In other words, if COMPOSE_PROFILES was set prior to running the above command, its value remains unchanged.
  • To check it out, visit http://localhost:8060/
• Shut down: ./gradlew :dockerComposeDown
  • To shut down only the api-gateway container:

    docker compose stop api-gateway
    docker compose rm -f api-gateway
    

Platform Base + Java App

• Prep: Start up the Platform Base setup (using instructions in the prior section)
• Start up: ./gradlew :app:dockerComposeUp (Note the :app, which will run the dockerComposeUp task in only the app Gradle project.)
  • Equivalent to cd app; docker compose up -d
  • Equivalent to docker compose -f app/docker-compose.yml up -d
  • After a couple of minutes, visit http://localhost:8110/v3/api-docs or http://localhost:8110/swagger
• Shut down: ./gradlew :app:dockerComposeDown
  • Equivalent to docker compose -f app/docker-compose.yml down
• Optionally, shut down the Platform Base setup (using instructions in the prior section)

Platform Base + Java App with Platform Microservices

• Prep: Start up the Platform Base setup (using instructions in the prior section)
• To run only the Lighthouse microservice: COMPOSE_PROFILES="lh" ./gradlew :app:dockerComposeUp
  • Equivalent to cd app; COMPOSE_PROFILES="lh" docker compose up -d
  • Equivalent to COMPOSE_PROFILES="lh" docker compose -f app/docker-compose.yml up -d
• To run all the Platform microservices: COMPOSE_PROFILES="svc" ./gradlew :app:dockerComposeUp
  • Equivalent to cd app; COMPOSE_PROFILES="svc" docker compose up -d
  • Equivalent to COMPOSE_PROFILES="svc" docker compose -f app/docker-compose.yml up -d
• Optionally, shut down the Platform Base setup (using instructions in the prior section)

Mocks

Containers defined in the Mocks setup are not needed for typical development, so they are not started by default.

• First, build the mock container images: ./gradlew -p mocks docker
• To run the Lighthouse API and Slack mocks: COMPOSE_PROFILES="lh,slack" ./gradlew -p mocks :dockerComposeUp
  • Equivalent to cd mocks; COMPOSE_PROFILES="lh,slack" ./gradlew :dockerComposeUp
  • Equivalent to cd mocks; COMPOSE_PROFILES="lh,slack" docker compose up -d
  • Equivalent to COMPOSE_PROFILES="lh,slack" docker compose -f mocks/docker-compose.yml up -d
• To run all the mocks: COMPOSE_PROFILES="all" ./gradlew -p mocks :dockerComposeUp

Examine the mocks/docker-compose.yml file to see what other profiles are available.

Without Docker Compose

If you want the mock to be available as localhost outside of the Docker Compose network, run it without Docker Compose -- for example:

• docker run -d -p 20100:20100 --name mock-slack va/abd_vro-mock-slack

Run specific containers

To run a container without the Platform Base, don't use Docker Compose. Instead run using Gradle task dockerStart, for example to run the Domain-CC App: ./gradlew domain-cc:cc-app:dockerStart. Prior to running the container, this task will automatically build the container image (./gradlew domain-cc:cc-app:docker). To shut down the container:

./gradlew domain-cc:cc-app:dockerStop
./gradlew domain-cc:cc-app:dockerRemoveContainer # Optional

Run specific Platform Base container

To run only a subset of the Platform Base, specify the containers declared in the docker-compose.yml file and use the docker compose command directly -- don't use the Gradle tasks. For example:

• To run only the Postgres DB and db-init containers: docker compose up -d postgres-service db-init.
• To shut down, run docker compose down.

Start All Containers

All containers are included in the all COMPOSE_PROFILE, so use that profile to start all containers in a given Docker setup.

• Set up: COMPOSE_PROFILES="all" ./gradlew dockerComposeUp (Note the lack of :, which will run dockerComposeUp in all relevant Gradle projects, starting from the root project).
• Shut down: COMPOSE_PROFILES="all" ./gradlew dockerComposeDown

Individually Start All Containers

To start each setup individually, start the Platform Base first; the others can be started in any order:

export COMPOSE_PROFILES="all"
./gradlew :dockerComposeUp   # start the Platform Base
./gradlew :app:dockerComposeUp
./gradlew :domain-xample:dockerComposeUp
./gradlew -p mocks :dockerComposeUp
...

To stop each setup individually, shut down the Platform Base last:

export COMPOSE_PROFILES="all" 
./gradlew :domain-xample:dockerComposeDown
./gradlew :app:dockerComposeDown
./gradlew -p mocks :dockerComposeDown
...
./gradlew :dockerComposeDown  # stop the Platform Base

Tip: set COMPOSE_PROFILES once

When a subset of containers across several setups is consistently used, set COMPOSE_PROFILES once and export it. The variable will be used for all subsequent commands, and any unknown profiles for a particular Docker setup is ignored.

For example, if development or testing involves only the API Gateway and Lighthouse API, then running:

export COMPOSE_PROFILES="gateway,lh"
./gradlew :dockerComposeUp :app:dockerComposeUp 
./gradlew -p mocks :dockerComposeUp

This will start the Platform Base setup with the API Gateway (due to COMPOSE_PROFILES="gateway" and :dockerComposeUp), the Java App with Lighthouse microservice (due to COMPOSE_PROFILES="lh" and :app:dockerComposeUp), and the Lighthouse API mock (due to COMPOSE_PROFILES="lh" and -p mocks :dockerComposeUp).

Prune all

Because Docker resources (containers, images, and volumes) may be overridden and recreated during development, occasionally clean up:

• To prune unreferenced Docker resources: ./gradlew :dcPruneAll
  • Equivalent to:

  docker container prune
  docker image prune
  docker volume prune