Backend Deployment

Overview

The Kin Conecta backend is built with Spring Boot 4.0.3 and Java 21. This guide covers running the backend locally for development and testing.

Prerequisites

Java 21

JDK 21 or higher is required. The project uses Java 21 language features.

MySQL Database

MySQL 8+ must be running with the Kin Conecta schema created.

Gradle

Gradle wrapper is included. No separate installation needed.

Application Config

Database credentials must be configured in application.properties.

Verify Java Installation

Before starting, verify Java 21 is installed:

java -version

Expected output:

java version "21.0.x"
Java(TM) SE Runtime Environment

If Java 21 is not installed, download it from:

Running the Backend

Navigate to Backend Directory

Open a terminal and navigate to the backend project directory:

cd backendKC

Configure Database Connection

Ensure your src/main/resources/application.properties is properly configured.See Configuration Guide for details.

Start the Application

Run the Spring Boot application using Gradle:

.\gradlew.bat bootRun

The application will compile and start. You should see output similar to:

2026-03-11 10:15:32.123  INFO --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8080 (http)
2026-03-11 10:15:32.130  INFO --- [           main] org.generation.KCv2Application          : Started KCv2Application in 5.234 seconds

Verify the Server is Running

The API is now available at:

http://localhost:8080

Test with a simple endpoint:

curl http://localhost:8080/api/languages

Build Configurations

The project uses Gradle with the following key configurations:

Gradle Build File

From build.gradle:

plugins {
    id 'java'
    id 'org.springframework.boot' version '4.0.3'
    id 'io.spring.dependency-management' version '1.1.7'
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

Key Dependencies

Spring Boot Starter Data JPA - Database access and ORM
Spring Boot Starter WebMVC - REST API framework
Spring Boot Starter Security - Authentication and authorization
MySQL Connector - MySQL JDBC driver
Lombok - Reduces boilerplate code
Spring Boot DevTools - Hot reload during development

Available Gradle Commands

# Windows
.\gradlew.bat bootRun

# Linux/Mac
./gradlew bootRun

API Endpoints

The backend exposes RESTful API endpoints for all resources. The system includes 195 CRUD routes across 39 controllers.

Base URL

http://localhost:8080

Example Endpoints

User Management

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

# Get user by ID
GET http://localhost:8080/api/users/{id}

# Create user
POST http://localhost:8080/api/users

# Update user
PUT http://localhost:8080/api/users/{id}

# Delete user
DELETE http://localhost:8080/api/users/{id}

Tours

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

# Get tour by ID
GET http://localhost:8080/api/tours/{id}

# Create tour
POST http://localhost:8080/api/tours

# Update tour
PUT http://localhost:8080/api/tours/{id}

# Delete tour
DELETE http://localhost:8080/api/tours/{id}

Languages

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

# Create language
POST http://localhost:8080/api/languages
Content-Type: application/json
{
  "languageCode": "es",
  "name": "Español"
}

FAQ

# Get all FAQ categories
GET http://localhost:8080/api/faq_categories

# Get all FAQ items
GET http://localhost:8080/api/faq_items

# Get FAQ item by ID
GET http://localhost:8080/api/faq_items/{id}

For a complete catalog of all 195 endpoints, refer to the ENDPOINTS.md file in the backend directory.

Testing the API

Using cURL

curl -X POST "http://localhost:8080/api/users" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "TOURIST",
    "fullName": "Ana Perez",
    "dateOfBirth": "1998-04-17",
    "email": "ana@example.com",
    "passwordHash": "hash_demo",
    "countryCode": "MX",
    "phoneNumber": "5512345678",
    "phoneE164": "+525512345678",
    "preferredLanguageCode": "es",
    "accountStatus": "ACTIVE"
  }'

Using Postman

Import the API collection (if available)
Set the base URL to http://localhost:8080
Configure headers: Content-Type: application/json
Test individual endpoints

Troubleshooting

Port Already in Use

If port 8080 is already occupied:

Option 1: Stop the process using port 8080
Option 2: Change the port in application.properties:
```
server.port=8081
```

Database Connection Errors

If you see Unknown database or connection refused errors, verify your database is running and configuration is correct.

Common causes:

MySQL server is not running
Schema name mismatch in application.properties
Incorrect credentials (username/password)
Database not created (run kinConnect.sql first)

Solution steps:

Verify MySQL is running:
```
mysql -u root -p
```
Check schema exists:
```
SHOW DATABASES LIKE 'KCv2';
```
Verify credentials in application.properties
Check connection URL matches your schema name

Java Version Mismatch

If you see errors about unsupported class file version:

Unsupported class file major version 65

This means Java 21 is required but an older version is installed. Install Java 21 and update your JAVA_HOME environment variable.

Gradle Build Failures

If the build fails:

Clean the project:
```
./gradlew clean
```
Delete the build directory manually if needed
Rebuild:
```
./gradlew build
```

Development Tips

Hot Reload

The project includes Spring Boot DevTools for automatic restart on code changes. Simply save your Java files and the application will restart automatically.

SQL Logging

SQL queries are logged to the console by default. This is configured in application.properties:

spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true

Disable for production by setting these to false.

Custom Build Directory

The project uses a custom build directory in the system temp folder to avoid permission issues:

def tempBuildDir = new File(System.getProperty('java.io.tmpdir'), 'BackendKC-build')
layout.buildDirectory.set(tempBuildDir)

Next Steps

Once the backend is running:

Frontend Deployment - Set up the frontend application
Configuration - Fine-tune application settings
Explore the API using Postman or cURL
Review the complete endpoint catalog in ENDPOINTS.md

Setup

Overview

Prerequisites

Java 21

MySQL Database

Gradle

Application Config

Verify Java Installation

Running the Backend

Build Configurations

Gradle Build File

Key Dependencies

Available Gradle Commands

API Endpoints

Base URL

Example Endpoints

Testing the API

Using cURL

Using Postman

Troubleshooting

Port Already in Use

Database Connection Errors

Java Version Mismatch

Gradle Build Failures

Development Tips

Hot Reload

SQL Logging

Custom Build Directory

Next Steps

Build docs developers (and LLMs) love

Setup

​Overview

​Prerequisites

Java 21

MySQL Database

Gradle

Application Config

​Verify Java Installation

​Running the Backend

​Build Configurations

​Gradle Build File

​Key Dependencies

​Available Gradle Commands

​API Endpoints

​Base URL

​Example Endpoints

​Testing the API

​Using cURL

​Using Postman

​Troubleshooting

​Port Already in Use

​Database Connection Errors

​Java Version Mismatch

​Gradle Build Failures

​Development Tips

​Hot Reload

​SQL Logging

​Custom Build Directory

​Next Steps

Build docs developers (and LLMs) love

Overview

Prerequisites

Verify Java Installation

Running the Backend

Build Configurations

Gradle Build File

Key Dependencies

Available Gradle Commands

API Endpoints

Base URL

Example Endpoints

Testing the API

Using cURL

Using Postman

Troubleshooting

Port Already in Use

Database Connection Errors

Java Version Mismatch

Gradle Build Failures

Development Tips

Hot Reload

SQL Logging

Custom Build Directory

Next Steps