Local development setup

This document provides a comprehensive guide for setting up and running the application in a local development environment. It covers IDE configuration, running dependencies, launching the application, and using essential development tools.

For initial setup and installation of prerequisites like Java and Docker, please refer to the Installation Guide.

IDE setup

A properly configured Integrated Development Environment (IDE) is crucial for productivity. We recommend using IntelliJ IDEA Ultimate or Visual Studio Code with the appropriate extensions.

Java 17 SDK Configuration

The project is built to run on Java 17. Your IDE must be configured to use a Java 17 SDK. The project includes a mise.toml file, which can automatically configure the correct Java and Maven versions if you have mise installed.

# mise.toml
[tools]
java = "17"
maven = "latest"

To configure this in IntelliJ IDEA:

1. Go to File > Project Structure > Project.
2. Set the SDK to a Java 17 installation.
3. Set the Language level to 17.

Lombok Plugin Installation

The project uses Project Lombok to reduce boilerplate code (e.g., getters, setters, constructors). It is essential to install the Lombok plugin for your IDE.

Gotcha: Without the Lombok plugin, your IDE will show compilation errors for missing methods (like .get...() or .set...()), even though the project will compile correctly with Maven.

1. IntelliJ IDEA: Go to File > Settings > Plugins, search for Lombok, and install it. You must also enable annotation processing by navigating to File > Settings > Build, Execution, Deployment > Compiler > Annotation Processors and checking Enable annotation processing.
2. VS Code: Install the Lombok Annotations Support for Java extension by Microsoft.

Maven Integration

The project uses Maven for dependency management and build automation. Modern IDEs have excellent Maven integration. After importing the project, the IDE should automatically detect the pom.xml and download the required dependencies. You can use the IDE's Maven panel to run lifecycle goals like clean, install, and package.

Running locally

The application depends on external services (a database and a message broker) which are managed via Docker Compose for a consistent development experience.

Starting Infrastructure with Docker Compose

Prerequisites: Docker and Docker Compose must be installed.

The docker-compose.yml file in the project root defines the necessary services: a MySQL database and a RabbitMQ message broker.

# docker-compose.yml
version: '3.8'

services:
  mysql:
    image: mysql:8.0
    container_name: ticketing-mysql
    environment:
      MYSQL_ROOT_PASSWORD: password
      MYSQL_DATABASE: ticketing
      MYSQL_USER: ticketing_user
      MYSQL_PASSWORD: changeme
    ports:
      - "3306:3306"
    volumes:
      - mysql-data:/var/lib/mysql
    # ... healthcheck

  rabbitmq:
    image: rabbitmq:3.12-management
    container_name: ticketing-rabbitmq
    environment:
      RABBITMQ_DEFAULT_USER: guest
      RABBITMQ_DEFAULT_PASS: guest
    ports:
      - "5672:5672"   # AMQP port
      - "15672:15672" # Management UI
    # ... healthcheck

volumes:
  mysql-data:

To start these services, run the following command from the project root:

docker-compose up -d

This will start the containers in detached mode. You can verify they are running with docker-compose ps.

Running Application from IDE

Once the infrastructure is running, you can start the Spring Boot application.

1. Activate the local profile: The application uses Spring Profiles to manage environment-specific configurations. For local development, the local profile must be active. This tells the application to load its configuration from application-local.properties. In your IDE's Run/Debug Configuration for the main application class, set the active profile.

   • In IntelliJ IDEA: In the Run/Debug Configurations dialog, under VM options, add: -Dspring.profiles.active=local.
   • Alternatively, you can set the environment variable SPRING_PROFILES_ACTIVE=local.

2. Run the main class: Locate the main application class (e.g., ItTicketingServiceApplication.java) and run its main method.

The console output should indicate that the local profile is active and the application has successfully connected to the database and message broker, starting on port 8080.

Hot Reload Configuration

For a faster development loop, we recommend using Spring Boot DevTools. If it's not already a dependency, add it to your pom.xml with <scope>runtime</scope> to ensure it's not packaged in the final artifact.

When DevTools is active, any change to a file on the classpath will trigger an automatic application restart, applying your code changes without a manual stop/start cycle.

Debugging Setup

To debug the application:

1. Set breakpoints in your code by clicking in the gutter next to the line numbers in your IDE.
2. Start the application in Debug Mode instead of Run Mode (usually a "bug" icon next to the "play" icon).
3. When you make a request that hits a line with a breakpoint, the application execution will pause, allowing you to inspect variables, evaluate expressions, and step through the code.

Development tools

These tools will help you interact with the running application and its dependencies.

HTTP Client for API Testing

The project includes an example-requests.http file containing sample requests for all major API endpoints. You can use this file directly with the built-in HTTP clients in IntelliJ IDEA or with the "REST Client" extension in VS Code.

Here are some example requests you can run:

### Create a new ticket
POST http://localhost:8080/api/tickets
Content-Type: application/json

{
  "title": "Laptop won't start",
  "description": "My laptop won't turn on after the latest Windows update.",
  "status": "OPEN",
  "priority": "HIGH",
  "requesterEmail": "john.doe@slalom.com",
  "assignedTo": null
}

### Get all tickets
GET http://localhost:8080/api/tickets

### Health check
GET http://localhost:8080/actuator/health

The example-requests.http file also includes examples for updating tickets (PUT), deleting tickets (DELETE), and filtering by query parameters (e.g., ?status=OPEN, ?requesterEmail=john.doe@slalom.com).

For more information on testing strategies, see the Testing Guide.

Database Management Tools

You can connect to the local MySQL database using any standard SQL client like DBeaver, DataGrip, or MySQL Workbench.

Use the following connection details, derived from docker-compose.yml and application-local.properties:

Parameter	Value
Host	localhost
Port	3306
Database/Schema	ticketing
Username	root (or ticketing_user)
Password	password (or changeme for ticketing_user)

Note: The docker-compose.yml creates two database users: root with password password, and ticketing_user with password changeme. The application is configured to use the root user by default in application-local.properties, but you can connect with either user for database management.

Note: The spring.jpa.hibernate.ddl-auto=update property in application-local.properties configures Hibernate to automatically create and update the database schema based on your JPA entities. This is convenient for development but should never be used in production.

RabbitMQ Management Console

The RabbitMQ container includes a web-based management UI for monitoring the message broker.

• URL: http://localhost:15672
• Username: guest
• Password: guest

In the console, you can inspect exchanges, queues, bindings, and monitor message flow. This is invaluable for debugging asynchronous processes. For details on the messaging architecture, refer to the Messaging Documentation.

Environment configuration

All local environment configuration is centralized in src/main/resources/application-local.properties.

Local Profile Activation

As mentioned, activating the local Spring profile is key. This ensures the application loads the correct datasource URLs, credentials, and other development-specific settings. If the application fails to start with database connection errors, the most likely cause is that the local profile is not active.

Development Property Overrides

The application-local.properties file contains all the necessary overrides for local development.

# src/main/resources/application-local.properties

# --- General ---
spring.application.name=it-ticketing-service
server.port=8080

# --- Local MySQL Database Configuration ---
spring.datasource.url=jdbc:mysql://localhost:3306/ticketing?createDatabaseIfNotExist=true
spring.datasource.username=root
spring.datasource.password=password
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

# --- JPA/Hibernate Configuration for Dev ---
spring.jpa.hibernate.ddl-auto=update # Creates/updates schema on startup
spring.jpa.show-sql=true              # Logs generated SQL to the console
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQLDialect
spring.jpa.properties.hibernate.format_sql=true

# --- Local RabbitMQ Configuration ---
spring.rabbitmq.host=localhost
spring.rabbitmq.port=5672
spring.rabbitmq.username=guest
spring.rabbitmq.password=guest

# --- RabbitMQ Custom Properties ---
rabbitmq.exchange.name=ticket.exchange
rabbitmq.queue.name=ticket.queue
rabbitmq.routing.key=ticket.routing.key

# --- Actuator Configuration ---
management.endpoints.web.exposure.include=health,info,metrics
management.endpoint.health.show-details=always

# --- Logging Configuration ---
logging.level.com.slalom.demo.ticketing=DEBUG
logging.level.org.springframework.amqp=DEBUG
logging.level.org.springframework.web=DEBUG

Port Configuration

The following ports are used by default in the local development environment. Ensure they are not in use by other processes on your machine.

Service	Port	Purpose
Application	8080	Main application HTTP port (REST API)
MySQL Database	3306	JDBC connection port
RabbitMQ	5672	AMQP protocol port for messaging
RabbitMQ UI	15672	Web-based management console