Installation

This document provides detailed instructions for setting up the development environment, installing dependencies, and building the IT Ticketing Service application. Following these steps will ensure a consistent and functional local setup for development and maintenance.

Installing Prerequisites

Before cloning and building the project, you must have the necessary runtime and build tools installed on your local machine. This project uses mise to manage tool versions, which is the recommended approach for ensuring environment consistency.

Important: The application's default configuration in application.properties points to a remote legacy MySQL database at legacydb.next26.slalomlab.com:3306. For local development, you will need either access to this database or to override the configuration to use a local instance (see Option 2 in the "Setting Up Dependencies" section below).

1. Java Development Kit (JDK)

The application is built and runs on Java 17. This is specified in the pom.xml:

<properties>
    <java.version>17</java.version>
</properties>

Recommended Installation (using mise):

The repository includes a mise.toml file that specifies the required Java and Maven versions.

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

1. Install mise.
2. Navigate to the project's root directory.
3. Run mise install. This command will automatically download and configure the correct JDK and Maven versions for your shell session.

Manual Installation:

If you prefer not to use mise, you can install a Java 17 distribution manually from providers like Adoptium (Temurin) or Oracle. Ensure that your JAVA_HOME environment variable points to the JDK 17 installation directory.

2. Apache Maven

Maven is used for dependency management and building the project.

Recommended Installation (using mise):

As mentioned above, running mise install in the project root will install the appropriate Maven version.

Manual Installation:

Download and install Maven (version 3.6+ is recommended) from the official Apache Maven website. Ensure the mvn command is available in your system's PATH.

3. Docker and Docker Compose (Recommended)

The project's primary dependencies, MySQL and RabbitMQ, can be easily managed using Docker. While not strictly required (you can connect to existing instances), it is the highly recommended path for a clean and isolated development environment.

The repository includes a docker-compose.yml file for this purpose.

• Install Docker Desktop for your operating system (Windows, macOS, or Linux). It includes both Docker Engine and Docker Compose.

Cloning the Repository

Repository Location

Obtain the source code by cloning the Git repository.

# Replace with the actual repository URL
git clone <repository-url>
cd it-ticketing-service

Directory Structure Overview

After cloning, familiarize yourself with the key files and directories:

• pom.xml: The Maven Project Object Model file. Defines project dependencies, plugins, and build settings.
• docker-compose.yml: Defines the local MySQL and RabbitMQ services for development.
• mise.toml: Specifies the exact tool versions (Java, Maven) for environment consistency.
• src/main/java: Contains the application's Java source code.
• src/main/resources: Contains non-code resources, including application.properties for configuration.
• src/test/: Contains all unit and integration tests.

Setting Up Dependencies

The application requires a running MySQL database and a RabbitMQ message broker.

Default Configuration: The src/main/resources/application.properties file is pre-configured to connect to:

• MySQL: Remote legacy database at legacydb.next26.slalomlab.com:3306 (database: ticketing, user: ticketing_user)
• RabbitMQ: Local instance at localhost:5672

You have two options for setting up these dependencies:

Option 1: Use Remote Legacy Database (Default Configuration)

If you have network access to the legacy database server (legacydb.next26.slalomlab.com), the application will work with the default configuration. You only need to set up RabbitMQ locally:

docker run -d --name ticketing-rabbitmq \
  -p 5672:5672 -p 15672:15672 \
  -e RABBITMQ_DEFAULT_USER=guest \
  -e RABBITMQ_DEFAULT_PASS=guest \
  rabbitmq:3.12-management

The RabbitMQ Management UI will be available at http://localhost:15672.

Option 2: Local Setup with Docker (For Development/Testing)

If you don't have access to the legacy database or prefer a fully local development environment, you can use the provided docker-compose.yml file to run both MySQL and RabbitMQ locally.

1. Navigate to the root of the cloned repository.

2. Run the following command to start the services in detached mode:

   docker-compose up -d

This command will pull the necessary images and start two containers: ticketing-mysql and ticketing-rabbitmq.

The docker-compose.yml file configures the services as follows:

# file: 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"
    # ...

  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
    # ...

The Docker Compose configuration includes a named volume (mysql-data) for the MySQL service, which persists your database data across container restarts. This means your local development data will be preserved when you stop and restart the containers.

Important: To use these local Docker containers, you must override the database URL in application.properties. Update the following property:

# Change from remote legacy database
# spring.datasource.url=jdbc:mysql://legacydb.next26.slalomlab.com:3306/ticketing

# To local Docker instance
spring.datasource.url=jdbc:mysql://localhost:3306/ticketing

The Docker services are configured with these connection details:

Service	Host	Port	Username	Password	Database/VHost	Notes
MySQL	localhost	3306	ticketing_user	changeme	ticketing
RabbitMQ	localhost	5672	guest	guest	/ (default)	Management UI at http://localhost:15672

Gotcha: If the docker-compose up command fails, it is likely because another process is already using port 3306, 5672, or 15672. Stop the conflicting process or modify the port mappings in docker-compose.yml.

Configuring Custom Database or RabbitMQ Instances

If you need to connect to different MySQL or RabbitMQ instances (other than the default remote legacy database or local Docker containers), update the connection properties in src/main/resources/application.properties.

For more detailed information on all available configuration options, please refer to the Configuration documentation.

Database Initialization

The application uses Spring Data JPA with Hibernate as the JPA provider. By default, Hibernate's ddl-auto mechanism is typically set to update, which means the database schema will be automatically created or updated to match the JPA entity definitions upon application startup. No manual SQL script execution is required for initial setup.

Building the Application

Once prerequisites are installed and dependencies are running, you can build the application using Maven.

Maven Build Command

From the root directory of the project, run the following command:

mvn clean package

This command performs the following actions:

1. clean: Deletes the target directory to ensure a fresh build.
2. package:
   • Compiles the Java source code.
   • Runs all tests located in src/test/.
   • Packages the compiled code and all dependencies into an executable JAR file.

Upon successful completion, the executable JAR will be located at target/it-ticketing-service-1.0.0.jar.

Build Troubleshooting

If you encounter issues during the build process, consider the following common problems:

• Lombok-related compilation errors: The project uses Lombok to reduce boilerplate code. While Maven handles this during the command-line build (via maven-compiler-plugin), your IDE requires a specific plugin to understand Lombok's annotations (@Data, @Builder, etc.).

  • Solution: Install the Lombok plugin for your IDE (e.g., IntelliJ IDEA, VS Code) and ensure annotation processing is enabled in your IDE's settings.

• Test Failures: Integration tests may fail if they cannot connect to the MySQL or RabbitMQ dependencies.

  • Solution:
    1. Ensure your Docker containers are running (docker ps).
    2. Verify that the connection properties in src/main/resources/application.properties (and src/test/resources/application.properties, if it exists) match your dependency setup.
    3. Check the logs of the Docker containers (docker logs ticketing-mysql) for any errors.

• Dependency Download Failures: Maven may fail to download dependencies due to network issues or a corporate proxy.

  • Solution: Configure your proxy settings in Maven's settings.xml file.

After a successful build, you are ready to run the application. For instructions, see the Running Locally documentation.