Running Locally

This document provides comprehensive instructions for setting up and running the IT Ticketing Service on a local development machine. It covers multiple approaches, from using the Maven build tool directly to leveraging Docker Compose for managing external dependencies.

Before proceeding, ensure you have the following prerequisites installed:

Java 17 or higher
Maven 3.6+
MySQL database (local instance or remote access)
RabbitMQ instance (local or remote)

Note: For local development, Docker and Docker Compose can be used to run MySQL and RabbitMQ locally (see the Docker Compose section below).

For a higher-level overview of the project, please refer to the Quick Start Guide.

Using Maven

Running the application directly with the Spring Boot Maven plugin is the quickest way to start the service, assuming its dependencies (MySQL, RabbitMQ) are already running and accessible.

The core command to launch the application is:

bash

mvn spring-boot:run

By default, Spring Boot will load configuration from src/main/resources/application.properties, which includes:

properties

# Database
spring.datasource.url=jdbc:mysql://legacydb.next26.slalomlab.com:3306/ticketing
spring.datasource.username=ticketing_user
spring.datasource.password=changeme

# RabbitMQ
spring.rabbitmq.host=localhost
spring.rabbitmq.port=5672

Using the Local Profile

For local development, the application includes an application-local.properties configuration file optimized for running on localhost. This profile configures:

MySQL database connection to localhost:3306 with root/password credentials
RabbitMQ connection to localhost:5672 with guest/guest credentials
Enhanced logging for debugging (DEBUG level for application and framework components)
Actuator endpoints for health monitoring
Hibernate DDL auto-update and SQL logging

To activate the local profile:

bash

mvn spring-boot:run -Dspring.profiles.active=local

This is the recommended approach for local development as it provides preconfigured settings that work with the Docker Compose setup described below.

Configuration Overrides

You can override any configuration property directly from the command line using -D arguments. This is useful for temporary changes, such as running on a different port or connecting to different database/messaging instances.

bash

# Example: Run the application on port 9090
mvn spring-boot:run -Dserver.port=9090

# Example: Override database connection
mvn spring-boot:run -Dspring.datasource.url=jdbc:mysql://localhost:3306/ticketing

Hot Reloading with DevTools

For an enhanced development experience, consider adding the spring-boot-devtools dependency to the pom.xml. When this dependency is present, any changes to classpath files will trigger an automatic application restart, significantly speeding up the development cycle.

xml

<!-- Add this to your pom.xml for automatic restarts -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-devtools</artifactId>
    <scope>runtime</scope>
    <optional>true</optional>
</dependency>

Using Docker Compose (Optional)

For local development without access to the remote legacy database and RabbitMQ instance, you can use Docker Compose to run MySQL and RabbitMQ locally. This provides a clean and isolated environment for development and testing.

The docker-compose.yml defines the following services:

yaml

# docker-compose.yml
version: '3.8'

services:
  mysql:
    image: mysql:8.0
    container_name: ticketing-mysql
    environment:
      MYSQL_ROOT_PASSWORD: password
      MYSQL_DATABASE: ticketing
    ports:
      - "3306:3306" # Exposes the MySQL port to the host machine
    volumes:
      - mysql-data:/var/lib/mysql # Persists database data across container restarts
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      timeout: 20s
      retries: 10

  rabbitmq:
    image: rabbitmq:3.12-management
    container_name: ticketing-rabbitmq
    environment:
      RABBITMQ_DEFAULT_USER: guest
      RABBITMQ_DEFAULT_PASS: guest
    ports:
      - "5672:5672"   # AMQP port for the application
      - "15672:15672" # Management UI port for browser access
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "ping"]
      timeout: 20s
      retries: 10

volumes:
  mysql-data:

Starting Services

Start the dependency containers in detached mode:
bash
```
docker-compose up -d
```
1
This command will pull the necessary images and start the MySQL and RabbitMQ containers in the background. The health checks ensure that the services are fully operational before they are marked as healthy.
Run the Spring Boot application using the local profile:
bash
```
mvn spring-boot:run -Dspring.profiles.active=local
```
1
The application-local.properties configuration is already set up to connect to the local Docker services with the correct credentials (root/password for MySQL, guest/guest for RabbitMQ).

Viewing Logs and Stopping Services

To view the logs for the dependency services:

bash

# Follow logs for all services
docker-compose logs -f

# Follow logs for a specific service (e.g., mysql)
docker-compose logs -f mysql

To stop and remove the containers:
bash
```
docker-compose down
```
1
To also remove the persistent MySQL data volume, use docker-compose down -v.

Running from JAR

You can also run the application as a standalone executable JAR file. This method is closer to how the application would be run in a production-like environment.

Build the JAR file:
bash
```
mvn clean package
```
1
The resulting JAR will be located at target/it-ticketing-service-1.0.0.jar.
Execute the JAR: Ensure your backing services (MySQL and RabbitMQ) are running. Then, run the JAR file using the java command.
bash
```
java -jar target/it-ticketing-service-1.0.0.jar
```
1

JVM Options and Arguments

When running from a JAR, you can easily pass standard JVM options (like memory settings) and Spring Boot arguments.

bash

# Example: Run with local profile
java -jar target/it-ticketing-service-1.0.0.jar --spring.profiles.active=local

# Example: Set max heap size to 512MB and override the server port
java -Xmx512m -jar target/it-ticketing-service-1.0.0.jar --server.port=8081

Verifying the Setup

Once the application is running, you can use the following steps to verify that everything is configured and connected correctly.

Checking Application Startup

Inspect the console output for the Spring Boot banner and the final log message indicating a successful startup:

...
2023-10-27T10:00:00.123 INFO 12345 --- [           main] c.s.d.t.ItTicketingServiceApplication   : Started ItTicketingServiceApplication in 5.432 seconds (process running for 6.789)

Testing Health Endpoints

The application includes Spring Boot Actuator, which exposes health check endpoints. For more details on monitoring, see the Monitoring Documentation.

Endpoint: GET http://localhost:8080/actuator/health

Expected Response: A 200 OK with a JSON body showing the status of the application and its connections to the database and message broker.

json

{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP",
      "details": {
        "database": "MySQL",
        "validationQuery": "isValid(0)"
      }
    },
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 499963174912,
        "free": 105778139136,
        "threshold": 10485760,
        "exists": true
      }
    },
    "ping": {
      "status": "UP"
    },
    "rabbit": {
      "status": "UP",
      "details": {
        "version": "3.12.12"
      }
    }
  }
}

Verifying Database Connectivity

Check Logs: Look for Hibernate logs in the console output, which indicate that JPA has successfully connected to the database and potentially created or updated the schema.
Connect to Database: Use a database client (e.g., DBeaver, MySQL Workbench, or the mysql CLI) to connect to the MySQL instance. When using the local profile, the credentials are root/password as configured in application-local.properties. Verify that the ticketing database exists and contains tables like ticket.

Confirming RabbitMQ Connection

Check Logs: Look for AMQP connection logs in the console, which will show a successful connection to the RabbitMQ broker.
Use Management UI: Open a web browser and navigate to the RabbitMQ Management UI at http://localhost:15672.
- Log in with the default credentials: guest / guest.
- Navigate to the Exchanges tab and verify that ticket.exchange has been created.
- Navigate to the Queues tab and verify that ticket.queue has been created and is bound to the exchange. This confirms that the application's startup logic for declaring RabbitMQ topology has executed successfully.

Running Locally ​

Using Maven ​

Using the Local Profile ​

Configuration Overrides ​

Hot Reloading with DevTools ​

Using Docker Compose (Optional) ​

Starting Services ​

Viewing Logs and Stopping Services ​

Running from JAR ​

JVM Options and Arguments ​

Verifying the Setup ​

Checking Application Startup ​

Testing Health Endpoints ​

Verifying Database Connectivity ​

Confirming RabbitMQ Connection ​

Running Locally

Using Maven

Using the Local Profile

Configuration Overrides

Hot Reloading with DevTools

Using Docker Compose (Optional)

Starting Services

Viewing Logs and Stopping Services

Running from JAR

JVM Options and Arguments

Verifying the Setup

Checking Application Startup

Testing Health Endpoints

Verifying Database Connectivity

Confirming RabbitMQ Connection