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

> Install KCloud-Platform-IoT with Spring Boot 4 and Spring Cloud 2025 easily. Follow our complete guide to set up the modular microservices architecture locally. Requires JDK 25 and Maven 3.9.11.

- Repository: [laokou/kcloud-platform-iot](https://github.com/koushenhai/kcloud-platform-iot)
- Tags: getting-started
- Published: 2026-03-05

---

**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`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/pom.xml):

- **JDK 25** – The top-level [`pom.xml`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/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.

```bash
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`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/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:

```bash
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`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/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`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/src/main/resources/application.yml):

```yaml
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`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/application.yml).

### Changing Nacos Server Address

To point services to a remote Nacos instance, modify [`application-dev.yml`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/application-dev.yml):

```yaml
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:

```yaml
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:

```bash
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`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/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`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/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`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/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.