Files

Du Wenbo 1636dea8f1 docs: add version management guide to README

Step-by-step instructions for releasing, downloading old versions,
comparing versions, and keeping version metadata in sync.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-06 09:08:03 +08:00

6.2 KiB

Raw Blame History

EMS Core Platform (ems-core)

Backend + shared libraries for all EMS customer projects

Current Version: 1.2.0 (see VERSIONS.json)

ems-core is the shared backend core for all EMS deployments. It provides the FastAPI backend, database models, data collectors, and customer hooks system. Frontend and Nginx are NOT included -- each customer repo provides its own frontend.

System Architecture

          +--------------------+
          |    Backend (Core)  |
          |    FastAPI         |
          |    :8000           |
          |    /api/v1/*       |
          +--------+-----------+
                   |
       +-----------+-----------+
       |                       |
+------v------+         +------v-------+
| TimescaleDB |         |    Redis     |
| PostgreSQL  |         |   Cache/Queue|
|   :5432     |         |   :6379      |
+-------------+         +--------------+

Note: Frontend and Nginx are NOT part of ems-core.
Each customer repo provides its own frontend and reverse proxy.

Tech Stack

Layer	Technology
Backend	FastAPI (Python 3.11)
ORM	SQLAlchemy 2.0 (async)
Database	TimescaleDB (PostgreSQL 16)
Cache	Redis 7
Task Queue	Celery + APScheduler
Migrations	Alembic
Container	Docker + Docker Compose

Quick Start

Prerequisites

Docker 20.10+
Docker Compose 2.0+

Start Services

# Clone
git clone http://100.69.143.96:3300/tianpu/ems-core.git
cd ems-core

# Configure
cp .env.example .env

# Start all services
docker compose up -d

# Initialize database
docker compose exec backend python scripts/init_db.py

Or use the quick-start script:

bash scripts/quick-start.sh

Access

Service	URL
Backend API	http://localhost:8000
API Docs (Swagger)	http://localhost:8000/docs
Health Check	http://localhost:8000/health

Role	Username	Password
Admin	admin	admin123

Change the default password after first login.

Local Development

cd backend

# Create venv
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install deps
pip install -r requirements.txt

# Start dev server (requires PostgreSQL and Redis running)
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Start only infrastructure:

docker compose up -d postgres redis

Project Structure

ems-core/
+-- backend/                    # Backend service
|   +-- app/
|   |   +-- api/v1/            # API routes
|   |   +-- collectors/        # Data collectors (Sungrow, Modbus, MQTT, HTTP)
|   |   +-- core/              # Core config
|   |   +-- hooks/             # Customer plugin system
|   |   +-- models/            # SQLAlchemy ORM models
|   |   +-- services/          # Business logic
|   |   +-- tasks/             # Background tasks (Celery + APScheduler)
|   |   +-- templates/         # Email templates
|   |   +-- main.py            # App entry point
|   +-- alembic/               # Database migrations
|   +-- tests/                 # Test suite
|   +-- Dockerfile
|   +-- requirements.txt
+-- scripts/                   # Utility scripts
|   +-- init_db.py             # Database initialization
|   +-- backfill_data.py       # Historical data backfill
|   +-- quick-start.sh         # Quick start script
+-- docker-compose.yml         # Dev environment
+-- docker-compose.prod.yml    # Production environment
+-- VERSION                    # Version file
+-- VERSIONS.json              # Version metadata
+-- .env.example               # Environment variables template
+-- CLAUDE.md                  # AI assistant guidelines
+-- README.md

API Endpoints

Main modules:

/api/v1/auth -- Authentication
/api/v1/devices -- Device management
/api/v1/energy -- Energy data
/api/v1/carbon -- Carbon emissions
/api/v1/alarms -- Alarm management
/api/v1/reports -- Reports
/api/v1/system -- System management

Full Swagger docs at http://localhost:8000/docs after starting the backend.

Version Management

We use Semantic Versioning (MAJOR.MINOR.PATCH) and git tags to manage releases.

Where Version Is Tracked

Version must be consistent across three places:

Location	Example	How to update
`VERSIONS.json`	`"project_version": "1.2.0"`	Edit the file
Git tag	`v1.2.0`	`git tag -a v1.2.0 -m "description"`
Gitea repo description	`[v1.2.0] EMS Core...`	Gitea Settings or API

Releasing a New Version

# 1. Update VERSIONS.json (set project_version, last_updated, notes)
#    For customer repos, also update core_version if core was updated

# 2. Commit the version bump
git add VERSIONS.json
git commit -m "chore: bump version to vX.Y.Z"

# 3. Create annotated tag (MUST be after VERSIONS.json is updated)
git tag -a vX.Y.Z -m "vX.Y.Z: brief description of this release"

# 4. Push commit AND tag together
git push origin main
git push origin vX.Y.Z

# 5. Update Gitea repo description
curl -X PATCH "http://<GITEA_HOST>/api/v1/repos/tianpu/<REPO>" \
  -H "Authorization: token <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"description": "[vX.Y.Z] Updated description"}'

Downloading a Specific Version

# Clone and checkout a specific version
git clone http://100.69.143.96:3300/tianpu/ems-core.git
cd ems-core
git checkout v1.1.0       # switch to v1.1.0 (detached HEAD)

# Or download as zip without cloning
curl -o ems-core-v1.1.0.zip \
  "http://100.69.143.96:3300/tianpu/ems-core/archive/v1.1.0.zip"

Viewing / Comparing Versions

# List all available versions
git tag -l

# See what changed between two versions
git diff v1.1.0 v1.2.0

# View a specific file at an old version
git show v1.1.0:VERSIONS.json

# View commit log between versions
git log v1.1.0..v1.2.0 --oneline

Switching Back to Latest

git checkout main          # go back to latest

Note

ems-core is the backend-only shared library. Each customer project (tp-ems, zpark-ems) owns its own frontend, deployed independently.

6.2 KiB Raw Blame History