Quick start

This guide provides the fastest path to get the IT Ticketing Service up and running on your local machine for development and testing. It leverages Docker Compose to simplify the setup of external dependencies.

For a more detailed guide on manual installation and configuration, please see the Installation Guide.

Prerequisites

Before you begin, ensure you have the following software installed and configured on your system.

Required Software

Software	Required Version	Installation Notes
Java (JDK)	17	The application is built and runs on Java 17. Ensure your JAVA_HOME environment variable is set correctly.
Apache Maven	3.6+	Used for dependency management and building the application. Verify with mvn -v.
Docker	20.10+	Required to run the application's dependencies (MySQL, RabbitMQ) in isolated containers.
Docker Compose	v2+	Used to orchestrate the multi-container Docker application. Verify with docker-compose version.
Git	Any recent version	Required to clone the project repository.

System Requirements

• A minimum of 8GB RAM is recommended to comfortably run the Docker containers and the Java application simultaneously.
• At least 5GB of free disk space for Docker images and volumes.

Database and Messaging Prerequisites

The application requires:

• MySQL Database: By default, the application is configured to connect to a remote database at legacydb.next26.slalomlab.com:3306. You'll need access credentials for this database.
• RabbitMQ Message Broker: Default configuration expects RabbitMQ at localhost:5672.

This quick start guide provides instructions for running with Docker Compose to set up local MySQL and RabbitMQ instances for development. If you prefer to use the default remote database or manually installed services, refer to the Running Locally Guide.

Running with Docker Compose

The docker-compose.yml file orchestrates the startup of all required backing services.

1. Start Dependent Services

Navigate to the root of the project directory in your terminal and run the following command to start the MySQL and RabbitMQ containers in detached mode:

docker-compose up -d

This command will:

1. Pull the mysql:8.0 and rabbitmq:3.12-management images if they are not available locally.
2. Create and start two containers: ticketing-mysql and ticketing-rabbitmq.
3. Create a persistent volume (mysql-data) to store database data across container restarts.

The docker-compose.yml is configured as follows:

# 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" # Exposes MySQL on the host machine
    volumes:
      - mysql-data:/var/lib/mysql
    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
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "ping"]
      timeout: 20s
      retries: 10

volumes:
  mysql-data:

2. Verify Services are Running

You can check the status of the containers to ensure they started correctly and are healthy.

docker-compose ps

You should see output indicating that both ticketing-mysql and ticketing-rabbitmq have a status of Up and their health checks are healthy.

You can also verify the services directly:

• RabbitMQ Management UI: Open your browser and navigate to http://localhost:15672. Log in with the default credentials guest / guest.
• MySQL Connection: You can connect to the database using any SQL client at localhost:3306 with user ticketing_user and password changeme.

3. Configure and Run the Application

The Spring Boot application needs to be configured to connect to the local Docker containers.

Important: The default application.properties in the repository points to a remote database at legacydb.next26.slalomlab.com:3306. For local development with Docker, you must update your src/main/resources/application.properties file to use localhost.

# src/main/resources/application.properties

# --- Database Configuration for Local Docker Setup ---
spring.datasource.url=jdbc:mysql://localhost:3306/ticketing?createDatabaseIfNotExist=true
spring.datasource.username=ticketing_user
spring.datasource.password=changeme
spring.jpa.hibernate.ddl-auto=update # Automatically creates/updates schema on startup

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

# --- Actuator Endpoints ---
management.endpoints.web.exposure.include=health,info,metrics

Once the configuration is verified, build and run the application:

# Build the application
mvn clean package

# Run using Maven Spring Boot plugin
mvn spring-boot:run

Alternatively, you can run the compiled JAR file directly:

java -jar target/it-ticketing-service-1.0.0.jar

The application will start, connect to the database and message broker, and be available on http://localhost:8080.

First API Request

With the application running, you can interact with its API. The following examples use curl, but any HTTP client will work.

1. Create Your First Ticket

Send a POST request to the /api/tickets endpoint to create a new IT support ticket.

curl -X POST http://localhost:8080/api/tickets \
-H "Content-Type: application/json" \
-d '{
  "title": "Cannot connect to VPN",
  "description": "My VPN client is stuck on the connecting screen and times out.",
  "status": "OPEN",
  "priority": "HIGH",
  "requesterEmail": "dev.user@slalom.com",
  "assignedTo": null
}'

Note: The assignedTo field can be null when creating a ticket (unassigned) or set to an email address to assign it immediately.

Expected Response (HTTP 201 Created): The API will respond with the newly created ticket object, including its server-assigned id and timestamps.

{
    "id": 1,
    "title": "Cannot connect to VPN",
    "description": "My VPN client is stuck on the connecting screen and times out.",
    "status": "OPEN",
    "priority": "HIGH",
    "requesterEmail": "dev.user@slalom.com",
    "assignedTo": null,
    "createdAt": "2023-10-27T10:00:00.000000Z",
    "updatedAt": "2023-10-27T10:00:00.000000Z"
}

2. View All Tickets

Send a GET request to retrieve a list of all tickets in the system.

curl http://localhost:8080/api/tickets

Expected Response (HTTP 200 OK): You will receive a JSON array containing the ticket you just created.

[
    {
        "id": 1,
        "title": "Cannot connect to VPN",
        "description": "My VPN client is stuck on the connecting screen and times out.",
        "status": "OPEN",
        "priority": "HIGH",
        "requesterEmail": "dev.user@slalom.com",
        "assignedTo": null,
        "createdAt": "2023-10-27T10:00:00.000000Z",
        "updatedAt": "2023-10-27T10:00:00.000000Z"
    }
]

3. Filter Tickets by Status or Requester

You can filter tickets using query parameters. The ticket status can be OPEN, IN_PROGRESS, or RESOLVED:

# Get all open tickets
curl "http://localhost:8080/api/tickets?status=OPEN"

# Get tickets by requester email
curl "http://localhost:8080/api/tickets?requesterEmail=dev.user@slalom.com"

4. Additional API Interactions

You are now ready to explore the rest of the API. Here are other key interactions:

• Get a ticket by ID: GET /api/tickets/1
• Update a ticket: PUT /api/tickets/1 with an updated JSON body
• Delete a ticket: DELETE /api/tickets/1
• Check application health: GET /actuator/health
• View application info: GET /actuator/info

For a complete list of endpoints, request/response schemas, and filter parameters, please consult the Ticket Endpoints API Reference.