How to Set Up KCloud-Platform-IoT with Spring Boot 4 and Spring Cloud 2025: Complete Installation Guide

KCloud-Platform-IoT requires JDK 25, Maven 3.9.11, and Spring Boot 4.0.3 with Spring Cloud 2025.0 to run its modular microservices architecture locally.

KCloud-Platform-IoT is an enterprise-grade, multi-tenant IoT platform built on the latest Spring Boot 4 and Spring Cloud 2025.0 (Spring Cloud 2025.1.0). The project follows a modular micro-service architecture and provides a ready-to-use stack that includes service registration, configuration management, gateway, security, and distributed tracing. This guide walks you through cloning the repository, building the project, and running individual services with the correct dependency versions.

Prerequisites for Spring Boot 4 and Spring Cloud 2025

Before building KCloud-Platform-IoT, verify your environment meets these minimum requirements enforced by the Maven Enforcer plugin in pom.xml:

• JDK 25 – The top-level pom.xml defines <java.version>25</java.version> and the Maven Enforcer plugin strictly enforces this version.
• Maven 3.9.11 – Required by the enforcer plugin to handle the complex dependency tree of Spring Cloud 2025.
• Docker (optional) – Used by the Docker Maven plugin to build container images for each microservice.
• Git – To clone the koushenhai/kcloud-platform-iot repository.

Clone and Build the Repository

Start by cloning the source code and building all modules. The project aggregates sub-modules including laokou-common, laokou-cloud, laokou-service, and KEdge-Gateway under a single parent POM.

git clone https://github.com/koushenhai/kcloud-platform-iot.git
cd kcloud-platform-iot
mvn clean install -DskipTests

The build downloads Spring Boot 4.0.3, Spring Cloud 2025.0, and Spring Cloud Alibaba 2025.1.0.0 as defined in the <dependencyManagement> section of pom.xml. Omit -DskipTests only if you want to execute the full integration test suite, which requires additional infrastructure services to be running.

Run Individual Microservices

Each microservice is a standard Spring Boot 4 application with a main class annotated with @SpringBootApplication. After building, you can start services individually using their generated JAR files.

Service	Main Class	JAR Location
Gateway	org.laokou.gateway.GatewayApp	laokou-cloud/laokou-gateway/target/laokou-gateway-*.jar
Auth	org.laokou.auth.AuthApp	laokou-service/laokou-auth/laokou-auth-start/target/laokou-auth-*.jar
IoT Core	org.laokou.iot.IotApp	laokou-service/laokou-iot/laokou-iot-start/target/laokou-iot-*.jar
Admin	org.laokou.admin.AdminApp	laokou-service/laokou-admin/laokou-admin-start/target/laokou-admin-*.jar
Report	org.laokou.report.ReportApp	laokou-service/laokou-report/laokou-report-start/target/laokou-report-*.jar
OSS	org.laokou.oss.OssApp	laokou-service/laokou-oss/laokou-oss-start/target/laokou-oss-*.jar
Network	org.laokou.mqtt.server.NetworkApp	laokou-service/laokou-network/laokou-network-start/target/laokou-network-*.jar

To start the Gateway service from the command line:

java -jar laokou-cloud/laokou-gateway/target/laokou-gateway-4.0.2.jar \
     --spring.profiles.active=dev \
     --spring.cloud.nacos.discovery.server-addr=127.0.0.1:8848

Configure Nacos and Infrastructure Services

KCloud-Platform-IoT uses Spring Cloud Alibaba Nacos for both configuration management and service discovery. The default Nacos address is 127.0.0.1:8848, defined in each service's application.yml.

Database Configuration

The platform uses PostgreSQL for business data and TimescaleDB for time-series IoT data. Configure connections in src/main/resources/application.yml:

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/kcloud_iot
    username: kcloud
    password: secret

Security and Monitoring

• Spring Security 7.0.3 – Implements OAuth2 Authorization Server with tokens stored in Redis.
• Spring Boot Admin 4.0.1 – Provides monitoring UI on port 9090 at http://localhost:9090.
• Redis – Required for token storage and caching; configure via spring.redis.host in application.yml.

Changing Nacos Server Address

To point services to a remote Nacos instance, modify application-dev.yml:

spring:
  cloud:
    nacos:
      discovery:
        server-addr: 192.168.10.100:8848
      config:
        server-addr: 192.168.10.100:8848

Docker Compose Quick Start

For local development, use the provided Docker Compose configuration to start infrastructure services (Nacos, Redis, PostgreSQL) and the Gateway:

services:
  nacos:
    image: nacos/nacos-server:2.2.3
    environment:
      - MODE=standalone
    ports:
      - "8848:8848"

  redis:
    image: redis:7
    ports:
      - "6379:6379"

  postgres:
    image: postgres:15
    environment:
      - POSTGRES_USER=kcloud
      - POSTGRES_PASSWORD=secret
      - POSTGRES_DB=kcloud_iot
    ports:
      - "5432:5432"

  gateway:
    image: koushenhai/kcloud-platform-iot-gateway:latest
    depends_on:
      - nacos
      - redis
      - postgres
    ports:
      - "8080:8080"

Run docker compose up -d from the project root, then access the gateway at http://localhost:8080.

Verify the Installation

After starting the Gateway service, verify health status using Spring Boot Actuator:

curl http://localhost:8080/actuator/health

A successful response shows "status":"UP" for all components. Each microservice exposes this endpoint on its respective port. Additionally, if you enabled Knife4j (Swagger UI) by adding @EnableKnife4j to your application class, access API documentation at http://localhost:8080/doc.html.

Summary

• JDK 25 is mandatory – The pom.xml enforces Java 25 via the Maven Enforcer plugin; older versions will fail the build.
• Modular architecture – Services like GatewayApp, AuthApp, and IotApp run independently with Spring Boot 4.0.3 and Spring Cloud 2025.0.
• Nacos integration – All services rely on Nacos at 127.0.0.1:8848 for configuration and discovery by default.
• Docker support – Use mvn docker:build to create container images or the provided Docker Compose for quick local setup.
• Security stack – OAuth2 Authorization Server runs on Spring Security 7.0.3 with Redis token storage.

Frequently Asked Questions

What Java version is required for KCloud-Platform-IoT?

JDK 25 is strictly required. The top-level pom.xml specifies <java.version>25</java.version> and the Maven Enforcer plugin blocks builds on older versions. This requirement supports the Spring Boot 4.0.3 and Spring Cloud 2025.0 baseline used throughout the platform.

How do I change the Nacos server address for all services?

Modify spring.cloud.nacos.discovery.server-addr and spring.cloud.nacos.config.server-addr in each service's src/main/resources/application-dev.yml. Alternatively, pass the address as a command-line argument when starting JAR files: --spring.cloud.nacos.discovery.server-addr=192.168.10.100:8848.

Can I run KCloud-Platform-IoT without Docker?

Yes. Docker is optional and only required if you want to build container images using the docker-maven-plugin. You can run all services locally using java -jar commands after building with Maven, provided you have local instances of Nacos, Redis, and PostgreSQL running.

Which microservices are essential for basic operation?

At minimum, you need three services running: Gateway (GatewayApp) for API routing, Auth (AuthApp) for authentication and authorization, and IoT Core (IotApp) for device management. These depend on Nacos for service discovery and Redis for token storage. Additional services like Admin, Report, and OSS can be started as needed for specific business functions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}