Skip to content

CLAUDE.md

Latest commit

 

History

History
119 lines (77 loc) · 7.39 KB

CLAUDE.md

File metadata and controls

119 lines (77 loc) · 7.39 KB
Raw

CLAUDE.md

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

Repository Overview

This is the Docker Compose configuration repository for TranscodeGroup's fleet/vehicle tracking platform. It does not contain application source code; it packages and orchestrates pre-built backend/frontend images and infrastructure services (MySQL, Redis, MongoDB, RabbitMQ, MinIO, nginx, SRS, etc.).

The repo is deployed to /home/docker on target servers. Runtime configuration and compose overrides live in /home/docker-compose, and persistent data is written to /data.

Common Commands

All compose commands are run from /home/docker-compose, where the top-level compose.yaml and .env files reside.

# Validate compose configuration and required environment variables
docker compose config

# Export resolved compose config for diff review
docker compose config > compose-stack.yaml

# Start the stack in the background
docker compose up -d

# Recreate a specific service after changing its config/image
docker compose up -d --force-recreate <service>

# Follow logs for a service
docker compose logs -f <service>

# Validate that initdb INSERT statements match CREATE TABLE column counts
node /home/docker/scripts/check-init-sql.js

When modifying mysql8/initdb/*.sql, run check-init-sql.js before committing to catch column/value mismatches.

High-Level Architecture

Modular Compose Layout

Each top-level directory (maintain/, jtt808/, bus/, video/, mysql8/, nginx/, etc.) contains one or more focused compose.yml fragments. These fragments are assembled by the example deployments in examples/ using Docker Compose include:

  • examples/track-http/compose.yaml — Tracker V2 single-node HTTP deployment.
  • examples/track-https/compose.yaml — Tracker V2 single-node HTTPS deployment.
  • examples/bus-http/compose.yaml / examples/bus-https/compose.yaml — Bus platform single-node deployments.
  • examples/video-storage/compose.yaml / examples/video-stream/compose.yaml — Distributed video storage/streaming nodes.

A deployment typically includes shared infrastructure (mysql8, redis, mongodb, rabbitmq, minio), one or more backend service fragments, nginx fragments, and optional video or web-downloader fragments.

Two Primary Products

  1. Tracker V2 (track)

    • maintain — Spring Boot backend (transcodegroup/maintain-server), the main API and device registry.
    • jtt808 — JT/T 808 device gateway (transcodegroup/jtt808-server), handles terminal connections and forwards to maintain.
    • video — SRS + RTP streaming stack for live video, playback, talk, and monitor.
    • nginx — Reverse proxy and static frontend host for the track web app.

  2. Bus

    • gateway_808_2019 — JT/T 808 gateway for the Bus product (transcodegroup/gateway-808-2019).
    • gateway_web — Spring Boot web backend (transcodegroup/gateway-web).
    • gateway_dispatch — Spring Boot scheduler (transcodegroup/gateway-dispatch).
    • gateway_jsatl12 — Active-safety alarm file gateway (transcodegroup/gateway-jsatl12).
    • nginx — Reverse proxy and static frontend host for the bus web app.

Both products share the same infrastructure services but use different MySQL databases (maintain vs cbus).

Configuration and Data Layout

  • /home/docker — This repository.
  • /home/docker-compose/compose.yaml — Deployment-specific composition, created from an examples/ template.
  • /home/docker-compose/.env — Runtime overrides, created from default.env.
  • /data — All persistent runtime data (MySQL data, logs, uploaded files, nginx html, SRS recordings, etc.).
  • /home/docker-compose/bus-override/ and /home/docker-compose/track-override/ — Frontend override directories. Files here are copied into /data/nginx/html/ when nginx starts. Use these to override _app.config.js, index-seo.html, favicons, and logos instead of editing /data/nginx/html/ directly.
  • /home/docker-compose/token/ — JWT RSA key pairs and ip2region.xdb.
  • /home/docker-compose/opt/ — Optional host binaries mounted into containers, e.g. ffmpeg, ffprobe, and ifv2mp4 for the jtt808 video-conversion tools.

MySQL Initialization

mysql8/compose.yml mounts mysql8/initdb/ into /docker-entrypoint-initdb.d. Scripts run once on the first container startup, before the application connects. The directory is split into table-definition and seed-data files per logical database (maintain, cbus, etc.). When altering these schemas, update the corresponding seed INSERTs and validate with scripts/check-init-sql.js.

Networking and Service Discovery

Services within the same compose project resolve each other by service name. Common aliases used in environment variables:

  • mysql8, redis, mongodb, rabbitmq, minio, nginx, jtt808, maintain, srs, rtp.

External access is exposed through nginx (ports 80/443 by default) and, for device protocols, directly through jtt808 / gateway_808_2019 / video RTP ports.

Frontend Deployment

Frontend artifacts are not built here. They are downloaded from CI artifacts using scripts/teamcity-download-artifact.sh or deployed from tagged GitHub releases using scripts/distar-beta-deploy.sh. See scripts/README.md and jtt808/README.md for exact commands.

Review Rules

When a pull request changes the following version variables in default.env / default.en.env, the reviewer must confirm that the corresponding MySQL initialization scripts under mysql8/initdb/ are still consistent with the new application version:

  • BUS_GATEWAY_VERSION — check mysql8/initdb/03-cbus-init-table.sql and mysql8/initdb/04-cbus-init-data.sql.
  • TRACK_MAINTAIN_VERSION — check mysql8/initdb/01-maintain-init-table.sql and mysql8/initdb/02-maintain-init-data.sql.

When either default.env or default.en.env is modified, the reviewer must check that the other file is updated in sync. The two files are Chinese and English templates for the same environment variables; version bumps, port changes, and new variables must be mirrored in both.

If the SQL init files are modified, run node scripts/check-init-sql.js to catch column/value mismatches. Any compose change must pass docker compose config.

These rules are also encoded in .github/pull_request_template.md.

Important Notes

  • Most compose fragments rely on environment variables marked {?required} in their image tags or env vars. Always run docker compose config before up to catch missing values.
  • MySQL init scripts only execute on a fresh data volume. To re-run them you must wipe /data/mysql8/data, which destroys all data.
  • The 100-init-partition-table.sql script uses USE maintain; and USE cbus; to create monthly partitions for large tables (position, alarm, depart_arrive).
  • HTTPS deployments need a valid certificate path in .env. For testing, use the built-in placeholder cert at ${DOCKER_DIR}/nginx/ssl/placeholder.
  • GitHub Actions in .github/workflows/ only manage project board automation and PR author assignment; they do not build or test this repo.

Related Documentation

  • README.md / README.en.md — Deployment quick-start.
  • scripts/README.md — Frontend artifact download and distar deployment scripts.
  • jtt808/README.md — FFmpeg and IFV-to-MP4 tooling setup.
  • default.env / default.en.env — Full list of configurable environment variables.