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

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.

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. 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 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

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:

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:

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:

# 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:

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:

docker compose restart ui

Resource Constraints Add deployment limits to docker-compose.yml for each service to prevent resource exhaustion:

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

Docker Health Checks Add health monitoring for critical databases. Edit docker-compose.yml to include:

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 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. 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 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 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 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.

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