CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

supOS-CE-Deploy is a Docker Compose-based deployment repository for supOS, an open-source Industrial Internet of Things (IIoT) platform. The repository contains configuration files, initialization scripts, and orchestration logic for deploying the platform.

Common Commands

Installation and Management

# Initial installation (main entry point)
bash bin/install.sh

# Start stopped containers
bash bin/start.sh

# Stop running containers
bash bin/stop.sh

# Uninstall (remove containers but keep data)
bash bin/uninstall.sh

# Complete cleanup including all data (use -f to skip confirmation)
bash bin/clean-all.sh
bash bin/clean-all.sh -f

Docker Compose Operations

# The compose file is selected based on OS_RESOURCE_SPEC in .env:
# - OS_RESOURCE_SPEC=1 → docker-compose-4c8g.yml (4 CPU cores, 8GB RAM)
# - OS_RESOURCE_SPEC=2 → docker-compose-8c16g.yml (8 CPU cores, 16GB RAM)

# Manual compose command example:
docker compose --env-file .env --env-file .env.tmp --project-name supos \
  --profile grafana --profile openclaw -f docker-compose-4c8g.yml up -d

# View container status
docker ps --filter "network=supos_default_network"

Architecture

Script Organization (bin/)

• install.sh - Main orchestration script that sources other scripts in sequence
• start.sh / stop.sh - Start/stop containers via docker network filter
• uninstall.sh - Remove containers while preserving volume data
• clean-all.sh - Full cleanup including volume data deletion (supports i18n via LANGUAGE)

Subdirectories

• bin/deb/ - Docker and yq installation scripts for Ubuntu
• bin/global/ - Shared functions (logging, profile selection with i18n)
• bin/init/ - Post-startup initialization scripts for individual services
  • init-openclaw.sh - OpenClaw AI agent configuration (requires AGENT_MODEL, LLM_API_KEY)
  • init-postgresql-sql.sh - Replaces GATEWAY_TOKEN in create_postgresql.sql
• bin/util/ - Utility scripts for IP selection, volume path handling, image loading

Configuration Flow

1. .env - User-configurable environment variables (VOLUMES_PATH, ENTRANCE_DOMAIN, LANGUAGE, etc.)
2. .env.tmp - Generated at runtime with computed values (BASE_URL, service profile flags, etc.)
3. mount/ - Template configurations copied to VOLUMES_PATH on first install
4. $VOLUMES_PATH/ - Runtime data and configuration storage

Service Profile Selection

The interactive installer uses bin/global/choose-profile-command.sh which:

• Supports 4c8g (chooseProfile1) and 8c16g (chooseProfile2) hardware profiles
• Provides i18n prompts based on LANGUAGE (en-US or zh-CN)
• Default timeout of 3 seconds applies to first selection prompt
• All step prompts use read -p with conditional Chinese/English text

Docker Compose Service Profiles

Services are organized by profiles to allow selective installation:

• Always installed: backend, frontend, nodered, emqx, keycloak, kong, postgresql, tsdb, chat2db, portainer
• Profile: grafana - Analytics and dashboards
• Profile: minio - Object storage
• Profile: fuxa - SCADA monitoring
• Profile: elk - Elasticsearch, Filebeat, Kibana logging stack
• Profile: gitea - Git service (8c16g only)
• Profile: mcpclient - MCP client service
• Profile: openclaw - AI agent service (requires internet connection)

Volume Initialization

• bin/init/init-volumes.sh - First-time setup: extracts npm caches, copies mount/ to VOLUMES_PATH
  • Creates openclaw directory and sets permissions (chown 1000:1000)
  • MUST execute before init-openclaw.sh
• bin/init/update-volumes.sh - Upgrade path for existing installations

Key Environment Variables

Variable	Description
VOLUMES_PATH	Directory for persistent data storage
ENTRANCE_DOMAIN	Frontend access domain/IP (do not use 127.0.0.1)
ENTRANCE_PORT	HTTP port (default: 8088)
OS_RESOURCE_SPEC	1 for 4c8g, 2 for 8c16g hardware profile
LANGUAGE	UI language: en-US or zh-CN (affects all prompts)
OAUTH_*	Keycloak OAuth configuration
AGENT_MODEL	OpenClaw model: zai/glm-5, zai/glm-4.7, moonshot/kimi-k2, minimax-cn/MiniMax-M2.5
LLM_API_KEY	API key for selected AGENT_MODEL provider

OpenClaw Integration

When the openclaw profile is selected, install.sh executes:

1. init-volumes.sh - Creates volumes including openclaw directory
2. init-openclaw.sh - Generates GATEWAY_TOKEN, replaces variables in openclaw.json, creates openclaw/.env
3. init-postgresql-sql.sh - Replaces GATEWAY_TOKEN in create_postgresql.sql for menu URL

The GATEWAY_TOKEN is generated once via openssl rand -hex 16 and synchronized across:

• $VOLUMES_PATH/openclaw/openclaw.json - Agent configuration
• $VOLUMES_PATH/openclaw/.env - Contains ZAI_API_KEY, MOONSHOT_API_KEY, or MINIMAX_API_KEY
• .env.tmp - Contains OPENCLAW_* variables for docker compose
• $VOLUMES_PATH/postgresql/init-scripts/create_postgresql.sql - Menu URL construction

Development Notes

• All scripts use bash and expect to run in Git Bash on Windows
• The platform URL format: ${ENTRANCE_PROTOCOL}://${ENTRANCE_DOMAIN}:${ENTRANCE_PORT}/home
• Default credentials: username supos, password supos
• All containers run on the supos_default_network bridge network
• Windows line endings (\r\n) are automatically cleaned from .env on script execution
• All user-facing prompts support i18n via LANGUAGE variable (check existing prompts before adding new ones)