Skip to main content
This guide will walk you through installing and running the User Management API on your local machine.

​
Prerequisites

Before you begin, ensure you have the following installed:

Java 21

Required for running the Spring Boot application

PostgreSQL

Database for persistent storage

Git

For cloning the repository

Docker (Optional)

For containerized deployment
This project uses Java 21 as specified in build.gradle. Make sure you have the correct version installed.

​
Installation Steps

1

Clone the Repository

Clone the project from GitLab:
git clone https://gitlab.com/ferney.estupinan/user-management-api.git
cd user-management-api
2

Set Up PostgreSQL Database

Create a PostgreSQL database for the application:
CREATE DATABASE user_db;
The application will automatically run Flyway migrations on startup to create the required tables.
Default credentials are postgres/password. You can override these in application-local.yaml or with environment variables.
3

Build the Project

Use the Gradle wrapper to build the project:
./gradlew build
This command will:
  • Download all dependencies
  • Compile the source code
  • Run all tests
  • Generate the JAR file in build/libs/
The first build may take a few minutes as Gradle downloads dependencies.
4

Run the Application

Start the application using Gradle:
./gradlew bootRun
Or run the JAR directly:
java -jar build/libs/user-management-api-0.0.1-SNAPSHOT.jar
The application will start on http://localhost:8080 by default.
5

Verify Installation

Check that the application is running by accessing the health endpoint:
curl http://localhost:8080/actuator/health
You should receive a response like:
{
  "status": "UP"
}

​
IDE Setup

​
IntelliJ IDEA

  1. Open IntelliJ IDEA and select File > Open
  2. Navigate to the cloned repository and select the root folder
  3. IntelliJ will automatically detect the Gradle project and import it
  4. Wait for dependency resolution to complete
  5. Enable annotation processing: Settings > Build, Execution, Deployment > Compiler > Annotation Processors and check “Enable annotation processing”
The project uses Lombok and MapStruct annotation processors. Make sure annotation processing is enabled in your IDE.

​
Eclipse

  1. Open Eclipse and select File > Import > Gradle > Existing Gradle Project
  2. Browse to the cloned repository and click Finish
  3. Eclipse will import the project and download dependencies
  4. Install the Lombok plugin: Download lombok.jar from projectlombok.org and run it

​
VS Code

  1. Open VS Code and install the following extensions:
    • Extension Pack for Java
    • Spring Boot Extension Pack
    • Lombok Annotations Support
  2. Open the project folder: File > Open Folder
  3. VS Code will automatically detect the Gradle project

​
Next Steps

Now that you have the application installed, you can:

Configuration

Learn how to configure the application

API Reference

Explore the API endpoints

Docker Setup

Run the application in Docker

Testing

Learn about the testing strategy

​
Accessing API Documentation

Once the application is running, you can access interactive API documentation:
Use Swagger UI to explore and test all API endpoints interactively.

​
Troubleshooting

If port 8080 is already in use, you can change it by setting the server.port property:
./gradlew bootRun --args='--server.port=8081'
Or set it in application-local.yaml:
server:
  port: 8081
Ensure PostgreSQL is running and the database user_db exists. Verify your connection settings in application.yaml:
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/user_db
    username: postgres
    password: password
This project requires Java 21. Check your Java version:
java -version
If you have multiple Java versions, set JAVA_HOME to point to Java 21:
export JAVA_HOME=/path/to/java-21
If Lombok annotations are not being processed:
  1. Ensure the Lombok plugin is installed in your IDE
  2. Enable annotation processing in IDE settings
  3. Invalidate caches and restart the IDE

Build docs developers (and LLMs) love

Get started for freeTalk to us