# How to Deploy KCloud-Platform-IoT in a Production Environment: Complete Docker-Compose Guide

> Deploy KCloud-Platform-IoT in production using Docker-Compose. This guide covers microservices, service discovery, databases, monitoring, and TLS for a robust setup.

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

---

**Deploy KCloud-Platform-IoT in a production environment using the Docker-Compose orchestration stack at `doc/deploy/docker-compose/`, which packages Spring Cloud microservices, Nacos service discovery, and multi-database infrastructure with integrated monitoring and TLS termination.**

The **koushenhai/kcloud-platform-iot** repository provides a production-ready microservices platform built on **Spring Cloud 2025.1.0**, **Spring Cloud Alibaba**, and **Spring Boot 4.0.3**. This guide explains how to deploy KCloud-Platform-IoT in a production environment using the comprehensive Docker-Compose configuration that orchestrates service discovery, API gateways, IoT protocol handlers, and observability tools.

## Production Architecture Overview

KCloud-Platform-IoT follows a **COLA**-style modular design deployed across isolated Docker containers. The production architecture consists of distinct logical layers orchestrated via the `iot_network` bridge defined in [`docker-compose.yml`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/docker-compose.yml).

**Core Infrastructure Layer:**
- **Nacos** (`registry.cn-shenzhen.aliyuncs.com/koushenhai/laokou-nacos:4.0.2-SNAPSHOT`) provides centralized service discovery and dynamic configuration on port `8848`
- **API Gateway** (`laokou-gateway`) handles request routing, Sentinel rate-limiting, and Spring Security on port `5555`
- **Authentication Service** (`auth`) manages OAuth2.0 token issuance and validation

**IoT Processing Layer:**
- **IoT Core** (`laokou-iot-start`) processes device-to-cloud protocols including MQTT, gRPC, and HTTP on port `10005`
- **Message Bus** (`kafka`, `pulsar`) enables asynchronous event streaming for decoupled communication

**Data Persistence Layer:**
- **Relational**: MySQL, PostgreSQL for business data
- **Time-Series**: InfluxDB, ClickHouse for device telemetry
- **Document/Search**: MongoDB, Elasticsearch with Kibana for full-text search
- **Cache**: Redis for session and metadata storage

**Observability Layer:**
- **Logging**: Logstash, Loki, Promtail for log aggregation
- **Metrics**: Grafana (port `3000`) for visualization, Prometheus for collection
- **Tracing**: Jaeger for distributed request tracing
- **MQTT Broker**: EMQX for device connectivity

**Frontend Delivery:**
- **UI Service** (`ui`) serves the Vue/UniApp management console over HTTPS on port `443` via NGINX

## Docker-Compose Production Configuration

The primary deployment artifact resides at [`doc/deploy/docker-compose/docker-compose.yml`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/doc/deploy/docker-compose/docker-compose.yml). This file defines container images, persistent volumes, network isolation, and service dependencies for production workloads.

**Key Configuration Elements:**

- **Persistent Storage**: Each database mounts data directories (e.g., `./mongodb/data`, `./mysql9/data`) to survive container restarts
- **Network Isolation**: All services attach to the dedicated `iot_network` bridge, preventing unauthorized cross-network access
- **Environment Management**: Shared variables in `env/common.env` combine with service-specific files (`env/gateway.env`, `env/iot.env`, `env/nacos.env`)
- **Privileged Mode**: Containers run with `privileged: true` and `tty: true` as per the development baseline; remove these flags after security hardening

**Critical Security Warning:** The default configuration contains hardcoded credentials such as `MYSQL_ROOT_PASSWORD=laokou123` and `NACOS_AUTH_TOKEN=laokou123`. Before production deployment, replace all default passwords in [`docker-compose.yml`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/docker-compose.yml) and environment files with cryptographically secure secrets managed via Docker secrets or HashiCorp Vault.

## Step-by-Step Production Deployment

Follow these steps to deploy KCloud-Platform-IoT in a production environment on a Docker host with minimum 16GB RAM and 40GB disk space.

**1. Prepare the Host Environment**

Install Docker Engine 24+ and Docker Compose v2. Ensure the host meets resource requirements for running 15+ containers simultaneously.

**2. Clone the Repository**

```bash
git clone https://github.com/koushenhai/kcloud-platform-iot.git
cd kcloud-platform-iot

```

**3. Configure Production Secrets**

Create secure environment overrides to replace default credentials:

```bash
mkdir -p doc/deploy/docker-compose/env
cat > doc/deploy/docker-compose/env/common.env <<EOF
JWT_SECRET=ReplaceWith256BitSecretKey
DB_ROOT_PASSWORD=ComplexPassword123!
NACOS_AUTH_TOKEN=SecureRandomTokenString
EOF

```

**4. Launch the Stack**

Navigate to the deployment directory and start all services:

```bash
cd doc/deploy/docker-compose
docker compose up -d

```

Docker Compose pulls images from `registry.cn-shenzhen.aliyuncs.com/koushenhai/` and initializes containers respecting the `depends_on` hierarchy (Nacos starts before Gateway, databases initialize before applications).

**5. Validate Service Health**

Verify critical endpoints return healthy status:

```bash

# Check Nacos registration center

curl -s http://localhost:8848/nacos/v1/ns/instance/list?serviceName=laokou-gateway

# Verify Gateway actuator

curl -s http://localhost:5555/actuator/health

# Test gRPC listener (default port 10111)

nc -zv localhost 10111 && echo "gRPC endpoint reachable"

```

Access the management interfaces:
- **Nacos Console**: `http://<host>:8848/nacos` (default login: `nacos` / `laokou123`)
- **Grafana Dashboard**: `http://<host>:3000` (default login: `admin` / `laokou123`)
- **Management UI**: `https://<host>` (requires TLS certificate configuration)

**6. Configure Runtime Parameters**

Edit service-specific environment files to enable production optimizations:

- **gRPC Configuration**: Set `servlet.enabled=false` in `env/iot.env` to isolate the gRPC listener from HTTP servlets, as detailed in `archive/docs/00.二开指南/02.指南/19.gRPC配置.md`
- **CORS Policies**: Restrict cross-origin settings in `env/gateway.env` to specific production domains
- **Sentinel Rules**: Enable flow control and circuit breaker configurations for the Gateway service

**7. Scale Services Horizontally**

Increase replica counts for high-traffic components:

```bash
docker compose up -d --scale iot=3 --scale gateway=2

```

Monitor replica status with `docker compose ps` to ensure all instances register correctly with Nacos.

## Production Hardening Checklist

Implement these security and reliability measures before handling production traffic.

**TLS Certificate Management**
Replace self-signed certificates in `ui/nginx/ssl/` with certificates from a trusted Certificate Authority. Update `ui/Dockerfile` lines 21-23 to reference your production certificates, then restart the UI container:

```bash
docker compose restart ui

```

**Resource Constraints**
Add deployment limits to [`docker-compose.yml`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/docker-compose.yml) for each service to prevent resource exhaustion:

```yaml
deploy:
  resources:
    limits:
      cpus: '2.0'
      memory: 4G
    reservations:
      memory: 2G

```

**Docker Health Checks**
Add health monitoring for critical databases. Edit [`docker-compose.yml`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/docker-compose.yml) to include:

```yaml
mysql:
  healthcheck:
    test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
    interval: 30s
    timeout: 10s
    retries: 5

```

**Network Security**
- Expose only necessary ports externally (Gateway `5555`, UI `443`, monitoring `3000`)
- Remove port mappings from internal services (databases, message queues) or bind to `127.0.0.1`
- Implement host firewall rules restricting access to the Docker network

**Log Rotation**
Configure host-level logrotate for volumes mounted at `./<service>/logs` to prevent disk saturation from container logs.

**Backup Strategy**
Schedule automated snapshots of persistent volumes:
- `./mongodb/data`
- `./mysql9/data`
- `./postgresql/data`
- `./minio/data`

**Secret Management**
Migrate all passwords from [`docker-compose.yml`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/docker-compose.yml) environment variables to Docker secrets or external vaults. Reference secrets in compose files using the `secrets` top-level element.

## Summary

Deploying KCloud-Platform-IoT in a production environment requires orchestrating multiple Spring Cloud microservices through the Docker-Compose configuration at [`doc/deploy/docker-compose/docker-compose.yml`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/doc/deploy/docker-compose/docker-compose.yml). Key takeaways include:

- The platform requires **Docker Engine 24+** with **16GB RAM minimum** to run the full stack including Nacos, Gateway, IoT services, and monitoring tools
- **Default credentials** (`laokou123`) must be replaced with secure secrets in `env/common.env` and [`docker-compose.yml`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/docker-compose.yml) before production use
- **Horizontal scaling** is supported via `docker compose up -d --scale iot=N` for handling high device connection volumes
- **TLS termination** occurs at the NGINX UI layer (`ui/Dockerfile`), requiring certificate updates in `ui/nginx/ssl/` for production HTTPS
- **gRPC configuration** for high-performance device communication requires setting `servlet.enabled=false` as documented in the gRPC configuration guide
- **Health validation** includes checking Nacos registration at port `8848`, Gateway actuator at port `5555`, and gRPC connectivity at port `10111`

## Frequently Asked Questions

### What are the minimum hardware requirements for deploying KCloud-Platform-IoT in production?

Production deployments require a minimum of **16GB RAM** and **40GB disk space** to accommodate the microservices stack, multiple databases (MySQL, PostgreSQL, MongoDB, ClickHouse), message brokers (Kafka/Pulsar), and monitoring infrastructure (Grafana, Prometheus, Loki). For high-availability scenarios with multiple replicas, allocate additional resources proportionally to the replica count specified in your [`docker-compose.yml`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/docker-compose.yml) scaling configuration.

### How do I update TLS certificates for the production UI deployment?

Replace the certificate files in the `ui/nginx/ssl/` directory with your production certificates from a trusted CA, ensuring the filenames match those referenced in `ui/Dockerfile` (typically lines 21-23). After updating the files, run `docker compose restart ui` from the `doc/deploy/docker-compose/` directory to reload the NGINX configuration without restarting the entire stack. For zero-downtime updates, consider using a reverse proxy or load balancer in front of the UI containers.

### Can I scale individual microservices independently in production?

Yes, the Docker-Compose setup supports independent horizontal scaling of microservices using the `--scale` flag. For example, run `docker compose up -d --scale iot=4 --scale gateway=2` to deploy four replicas of the IoT service and two Gateway instances. Each replica automatically registers with the Nacos service registry (`port 8848`) for load balancing. Ensure you define resource limits in [`docker-compose.yml`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/docker-compose.yml) using the `deploy.resources.limits` syntax to prevent container resource contention during scaling operations.

### Where are the persistent data volumes stored in the production deployment?

Persistent data is stored in host-mounted directories relative to the `doc/deploy/docker-compose/` path. Key volumes include `./mysql9/data` for relational data, `./mongodb/data` for document storage, `./minio/data` for object storage, and `./elasticsearch/data` for search indexes. These directories survive container restarts and updates. Implement a backup strategy that snapshots these directories regularly, and never delete them during routine maintenance to prevent data loss.