# Open supOS Deploy

**Repository Path**: Yu-xinqiang0413/supos-ce-deploy

## Basic Information

- **Project Name**: Open supOS Deploy
- **Description**: Open supOS  肩负“变革工业软件、升华数字体验”的使命而生。

面向工业与智慧城市，我们推出新一代 IIoT 平台——Open supOS,助您连接现场、分析数据、重塑工厂运营。通过高效的数据利用，全面提升数字化能力，解锁更智能的洞察。supOS 社区版现已发布，立即下载体验！

我们不仅在打造解决方案，更在重新想象未来的可能性，突破边界，去创造一个前所未有的世界。
- **Primary Language**: Shell
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: https://www.supos.com/product/supos/ce
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 46
- **Created**: 2026-09-29
- **Last Updated**: 2026-10-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# supOS: An Open-Source IIoT Platform

[English](README.md) | [中文](README-CN.md)

---

## Introduction
supOS is an open-source Industrial Internet of Things (IIoT) platform built around a Unified Namespace (UNS) for connecting industrial data. This repository deploys the platform backend with **OpenResty**, **Keycloak**, **Node-RED**, **EMQX**, and **PostgreSQL/TimescaleDB**, plus the management tools and optional services described below.

## Platform Architecture

### Core Components

The [4-core/8-GB](docker-compose-4c8g.yml) and [8-core/16-GB](docker-compose-8c16g.yml) Compose files define the same service set, with different resource settings. Without optional profiles, both define nine services: `backend`, `nginx`, `nodered`, `emqx`, `postgresql`, `tsdb`, `keycloak`, `portainer`, and `chat2db`.

- **Application and gateway**: `backend` provides platform APIs. `nginx` runs **OpenResty**, serves the frontend build and plugin assets, and proxies requests using the shipped [routes and Lua access handlers](mount/nginx/). There is no separate frontend service. The `kong` network alias and Konga display metadata are compatibility remnants, not deployed Kong/Konga services.
- **IoT data and identity**: **EMQX** provides MQTT messaging, **Node-RED** provides flow-based integration, and **Keycloak** provides SSO and identity management.
- **Separate data stores**: `postgresql` holds platform metadata and the Keycloak database, as well as Grafana's database when enabled. `tsdb` holds time-series data. Both use the TimescaleDB/PostgreSQL 17 image, but have separate persistent directories and [metadata](mount/postgresql/init-scripts/) / [time-series](mount/tsdb/init-scripts/) initialization scripts.
- **Management tools and Docker access**: **Chat2DB** provides a database UI; **Portainer** provides container management. `backend` and `portainer` mount the host Docker socket, as does the optional `pi-coding-agent`; these services depend on host Docker access.
- **Optional services**: **Grafana** dashboards use the `grafana` profile, **MinIO** S3-compatible object storage uses `minio`, and the **Pi coding agent** AI assistant uses `pi-agent` (service `pi-coding-agent`). The [installer's default selection](bin/global/choose-profile-command.sh) enables Grafana; MinIO and the AI assistant require custom selection. Bare Compose without profiles does not enable any of these three.

Neither Compose file deploys **Kong**, **Konga**, **TDengine**, **Elasticsearch**, **Filebeat**, **Kibana**, or **Hasura**. Historical architecture diagrams and remaining integration routes (such as Hasura routes) describe broader or earlier integrations; they do not establish that those services are installed.

---

## Installation

Before installing or upgrading, run the read-only deployment doctor:

```bash
bash bin/doctor.sh
```

See [Deployment doctor](docs/deployment-doctor.md) for checks, JSON output,
and exit codes.
After installation, `bash bin/doctor.sh --runtime` also checks the selected
services' container state and health without changing them.

### 1.Linux

#### 1.1 Operating Environment
- **Operating System**: Currently tested on Ubuntu Server 24.04 with Docker. We welcome feedback on other OS distributions.
- **Docker**: We assume you have Docker (with `docker compose` and `buildx`) installed. Our tested versions:
  - Docker Engine - Community: 27.4.0
  - Docker Buildx: v0.19.2
  - Docker Compose: v2.31.0
  - containerd: 1.7.24
    
#### 1.2 Usage
1. **Clone the project using Git Bash**:
   ```bash
   git clone <this repo>
   ```
2. **Modify the environment variables in the `.env` file**:
   - Navigate to the `supos-ce-deploy` directory and edit the `.env` file.
   - Update `VOLUMES_PATH` (directory for storing project data).
   - Update `ENTRANCE_DOMAIN` (frontend entry domain/IP address).
   - Modify other variables as needed.

3. **Start the project**:
   ```bash
   bash bin/install.sh
   ```
   - Wait for containers to pull and initialize. The first run may take a few minutes.
     
   If you don’t have Docker installed yet, our scripts can help set it up for Ubuntu Server 24.04. For other operating systems, please refer to the official Docker documentation.

### 2.Windows

#### 2.1 Operating Environment
- Install the latest version of **Docker Desktop** and **Git** on Windows 10 or Windows 11.
- It is recommended to perform all operations in **Git Bash**.

#### 2.2 Usage
1. **Clone the project**:
   ```bash
   git clone <this repo>
   ```
2. **Edit environment variables in the .env file**:
   - VOLUMES_PATH (directory for storing project data)
   - ENTRANCE_DOMAIN (Do not use 127.0.0.1)
   - Any other required variables per your environment

3. **Start the project**:
   ```bash
   bash bin/install.sh
   ```
   - Wait for containers to pull and initialize. This may take a few minutes on first run.

### 3.Access the Platform
   - Visit `http://<YOUR-DOMAIN>:<YOUR-PORT>` in your browser (based on ENTRANCE_DOMAIN and ENTRANCE_PORT in `.env`).
   - Open the EMQX Dashboard through the authenticated platform gateway at `/emqx/home/`. Host port `18083` is no longer published by default; MQTT and MQTT-over-WebSocket ports remain published. If an external EMQX management client requires direct access, add an explicit Compose port override after securing the dashboard credentials and network access.

### 4.Restarting or rebuilding services
   - For day-to-day restarts use `bash bin/start.sh` and `bash bin/stop.sh`. They start/stop the existing containers as-is and do not re-resolve environment variables.
   - If you need to rebuild services with `docker compose` directly (e.g. after changing `docker-compose-*.yml`), you must pass **both** env files. `BASE_URL` and several other variables used by the keycloak/nginx/minio services are generated by the installer into `.env.tmp` and do not exist in `.env`:

     ```bash
     docker compose --env-file .env --env-file .env.tmp \
       --project-name supos --profile grafana --profile minio \
       -f docker-compose-8c16g.yml up -d
     ```

     Without `--env-file .env.tmp` the keycloak container fails to start with `Provided hostname is neither a plain hostname nor a valid URL`, because `BASE_URL` resolves to empty.

## License
   - This project is distributed under the Mulan Permissive Software License v2 (MulanPSL-2.0). See LICENSE for details.

## Contact
   - If you have questions, open an issue or email us.
     
# Contributors

We gratefully acknowledge the following individuals for their contributions to this project:

- **Wenhao Yu** – Architecture  
- **Liebo** – UNS  
- **Kangxi & Lifang Sun** – Backend  
- **Minghe Zhuang** – Node-RED  
- **Wangji Xin** – Grafana  
- **Fayue Zheng & Yue Yang** – Frontend, Generative UI  
- **Yanqiu Liu** – McpClient