Local Dev Environment
The local dev environment is a minimal setup based on Docker Compose for running the Microservice Dungeon locally.
Use cases include the continued development of the core services, creating a custom player, or running codefights
locally.
| Artifacts | Links |
|---|---|
| Repository | https://gitlab.com/microservice-dungeon/infrastructure/deployments/local-dev-env |
Table of contents
About
The local dev environment is a minimal configuration for running the MSD locally in Docker.
For this two Docker Compose files are required: The first file initializes the infrastructure, the second starts the actual services - also refered to as the Core-Services. The infrastructure includes the components required to run and monitor the Core-Services - namely Kafka as the messaging broker, PostgreSQL as the primary database, and the monitoring stack, consisting of Prometheus and Grafana.
Connecting to the Environment
The local dev environment essentially covers three main use cases: Debugging the Core-Services, running a custom Player locally, and to stage a code-fight between multiple players.
Service Debugging
There are to options available for debugging a Core-Service:
A remote debugger can either be used to connect to the JVM’s debug agent running inside the container for placing
breaking points inside the code.
Alternatively, Core-Services can also be run locally directly from IntelliJ and connect to the other running inside
the Local Dev Env via localhost.
The necessary ports required for this are configured and exposed.
It is important to stop the corresponding container inside the Local Dev Env beforehand to prevent conflicts.
Player Deployment
Deploying a player is identical to running a Core-Service.
Players can either be deployed as containers alongside the Core-Services, or run locally from IntelliJ.
In both cases, the existing configuration can be used as a reference.
Accessible Services
The following table shows a listing of all services accessible from localhost.
| Service | Port | Description |
|---|---|---|
| Kafka | 29092 | Advertised listener for external connections outside of docker. |
| PostgreSQL | 5432 | Service endpoint. |
| Prometheus | 3001 | Prometheus dashboard. |
| Grafana | 3000 | Grafana dashboard. |
| Game-Service | 8080 | Service endpoint. |
| Game-Service | 9080 | JVM Debug agent endpoint. |
| Outbox-Service (Game) | 8081 | Service endpoint. |
| Outbox-Service (Game) | 9081 | JVM Debug agent endpoint. |
Getting Started
To get started with the Local Dev Env, clone the repository and follow the instructions below.
Prerequisites
Running the Local Dev Env has the following minimum requirements:
- Docker(-Desktop) or an equivalent OCI Container Runtime with Docker Compose installed
- 4 CPU Cores
- 10GB RAM
Hint: Make sure to check your resource configuration when using Docker-Desktop.
Starting the Environment
First, start the Infrastructure-Services.
Keep in mind, that ‘kafka-init’ is a one time job.
Therefore, it is intended that this container exits.
docker compose -f compose-infrastructure.yaml up -d
Then, start the Core-Services.
docker compose -f compose-core-services.yaml up -d
Make sure all Services are running and are healthy before you continue.
After that, you can start your player if you wish to.
Access Grafana Metrics
Infrastructure- and Core-Services expose metrics, that are collected by Prometheus and are visualized using Grafana.
The Grafana UI can be accessed via localhost:3000.
The default login is admin admin.
Metrics are visualized in Grafana using dashboards. These are not loaded automatically and must be imported manually once. They can be found under /config/grafana/dashboards/. Prometheus must be selected as the data source.
A Docker volume is configured for Grafana so that all dashboards should remain persistent even after a restart.
Shutting down the Environment
To shut down the Local Dev Env, stop the Services in the opposite order.
docker compose -f compose-core-services.yaml down
docker compose -f compose-infrastructure.yaml down