UBA Installation Guide

This document guides you through setting up the GoWind UBA local development environment from scratch: environment preparation, dependency services, database initialization, starting the three services, and starting the frontend.

Read System Architecture first to learn about the three services and their dependencies, and to understand the two modes: "libs_only (dependencies only) vs full_deploy (full stack)".

1. Environment Requirements

One-Click Installation Scripts

The repository provides environment installation scripts (backend/scripts/env/):

2. Get the Code

git clone https://github.com/tx7do/go-wind-uba.git
cd go-wind-uba

3. Start Dependency Services

Two Docker deployment modes:

Linux / macOS

cd backend
chmod +x scripts/**/*.sh

# Start middleware dependencies only (recommended for development)
./scripts/docker/libs_only.sh

# Or: one-click full deployment (middleware + backend services)
./scripts/docker/full_deploy.sh

Windows (PowerShell as Administrator)

cd backend
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser   # allow script policy on first run

.\scripts\docker\libs_only.ps1
# or
.\scripts\docker\full_deploy.ps1

Dependency containers include: postgres, redis, etcd, minio, jaeger, kafka, doris-fe, doris-be, superset. See Docker Deployment for details.

4. Initialize Databases

1. PostgreSQL (business database)

⚠️ Important: UBA has no hand-written PostgreSQL schema.sql — the table structures are generated by the Ent ORM. You only need to create the database and load the seed data.

# 1) Create the database (the name follows dbname in data.yaml, default gw_uba)
psql -h localhost -U postgres -c "CREATE DATABASE gw_uba;"

# 2) On first service startup, migrate: true in data.yaml automatically creates tables (based on the ent schema)
#    Seed dictionary data:
psql -h localhost -U postgres -d gw_uba -f sql/postgresql/default-data.sql

Docker compose has unified POSTGRES_DB=gw_uba (consistent with the services' data.yaml), so it works out of the box. For manual deployment (non-Docker), you need to run CREATE DATABASE gw_uba yourself; make sure the database name matches dbname in data.yaml (see Configuration Reference for details).

2. OLAP Engine (Doris / ClickHouse, pick one)

Apache Doris is used by default (decided by UseClickHouse = false):

# Doris (default): connect to the FE's port 9030 via the MySQL protocol
mysql -h localhost -P 9030 -u root < sql/doris/1_base_tables.sql
mysql -h localhost -P 9030 -u root < sql/doris/02_kafka_tables.sql   # set up Routine Load to consume Kafka

# Or ClickHouse (requires changing UseClickHouse to true and recompiling first)
clickhouse-client --queries-file sql/clickhouse/1_base_tables.sql
clickhouse-client --queries-file sql/clickhouse/02_kafka_tables.sql  # set up Kafka engine tables + materialized views to consume Kafka

The two 02_kafka_tables.sql scripts each set up the "consume Kafka → write to fact tables" jobs for the corresponding engine (Doris Routine Load / ClickHouse Kafka engine tables + materialized views). They are key to data ingestion and must be executed. See System Architecture · Kafka Consumption Mechanism for details.

5. Start the Backend Services

cd backend

# Install dependencies
go mod tidy

# Initialize the development environment (install protoc plugins and CLI tools: buf / wire / ent etc.)
make init

# Generate code (ent + wire + api + openapi)
make gen

# Build all services
make build

# Run the three services separately (one terminal each)
go run ./app/core/service/cmd/server/       -c ./app/core/service/configs
go run ./app/admin/service/cmd/server/      -c ./app/admin/service/configs
go run ./app/collector/service/cmd/server/  -c ./app/collector/service/configs

Service Listening Ports

Verification: visit the Admin Swagger (enable_swagger: true); after Core registers with etcd, it is discovered by Admin/Collector.

6. Start the Frontend

cd frontend/admin

# Install dependencies
pnpm install

# Start the dev server
pnpm dev

After startup, visit the admin console; by default it requests the Admin Service (5600).

7. First Integration Self-Check

1. Log in to the admin console → "Data Collection / App Management", create a new app, and obtain the appId + appSecret.
2. Use the Web SDK (or frontend/sdk/web/uba/test.html) to report an event to the Collector (5700) via POST /uba/v1/report, and confirm the response is 200 with no failedCount.
3. Data ingestion self-check: reported data is automatically loaded by the OLAP engine's virtual tables consuming Kafka (Doris uses Routine Load; ClickHouse uses Kafka engine tables). If queries return nothing during integration, first confirm the corresponding consumption job has been created and is running normally (Doris: SHOW ROUTINE LOAD). See System Architecture · Kafka Consumption Mechanism for details.

8. Common Commands Quick Reference

cd backend
make init       # install protoc plugins + CLI tools
make api        # generate Protobuf API code (Go + struct tags)
make openapi    # generate OpenAPI / Swagger docs
make ts         # generate the TypeScript client (only admin protos as input)
make ent        # generate ent entity code (in each service directory)
make wire       # regenerate dependency injection (wire_gen.go)
make gen        # = ent + wire + api + openapi (not including ts)
make build      # compile all services
make build_only # compile only, without code generation
make test       # run tests
make lint       # linting
make docker-libs# start dependencies with Docker Compose
make docker-up  # full deployment with Docker Compose

Commands like ent / wire live in backend/app.mk (included by each service's app.mk) and can be run individually under app/<svc>/service/. For the full command semantics, see Code Generation Pipeline.

9. Environment Script Notes

• libs_only: the first choice for development. Middleware runs in Docker, while the three backend services are debugged in the IDE/terminal with go run, making breakpoints and hot restarts convenient.
• full_deploy: one-click full stack. Suitable for demos, acceptance testing, or quickly verifying the entire chain.

10. Related Documentation

• System Architecture
• Code Generation Pipeline
• Docker Deployment
• Configuration Reference