Environment Setup

Complete environment setup guide for RecordPlatform from scratch.

Prerequisites

Host Requirements

Resource	Minimum	Recommended
CPU	4 cores	8 cores
Memory	8 GB	16 GB
Disk	40 GB	100 GB SSD
OS	Ubuntu 20.04+ / CentOS 8+ / macOS 12+	Ubuntu 22.04 LTS

Software Requirements

Software	Version	Purpose
Docker	20.10+	Infrastructure containerization
Docker Compose	2.0+	Container orchestration
Java	21 (LTS)	Backend services
Maven	3.8+	Java build
Node.js	20+	Frontend build
pnpm	10+	Frontend package manager
Git	2.30+	Version control

Step 1: Configure Environment Variables

# Clone the repository
git clone https://github.com/SoarCollab/RecordPlatform.git
cd RecordPlatform

# Copy the environment template
cp .env.example .env

Edit .env and update key settings:

# Must change before starting infrastructure
JWT_KEY=<random-string-at-least-32-chars>
DB_PASSWORD=<database-password>
REDIS_PASSWORD=<redis-password>
RABBITMQ_USERNAME=<rabbitmq-username>
RABBITMQ_PASSWORD=<rabbitmq-password>
NACOS_USERNAME=<nacos-username>
NACOS_PASSWORD=<nacos-password>
NACOS_AUTH_TOKEN=<base64-random-token-at-least-32-bytes>
NACOS_AUTH_IDENTITY_KEY=<nacos-identity-key-name>
NACOS_AUTH_IDENTITY_VALUE=<nacos-identity-secret>
S3_ACCESS_KEY=<minio-access-key>
S3_SECRET_KEY=<minio-secret-key>

# Optional: adjust for your environment
SPRING_PROFILES_ACTIVE=local   # local / dev / prod

WARNING

Do not use .env.example placeholder values on any shared or server host. The infrastructure compose file fails fast when required secrets are missing, and all passwords/tokens above must be replaced with strong environment-specific values.

docker-compose.infra.yml binds published service ports to 127.0.0.1 by default through INFRA_BIND_ADDRESS and OBSERVABILITY_BIND_ADDRESS. Keep this default on servers and expose only the application-facing endpoints through a firewall, VPN, SSH tunnel, or authenticated reverse proxy. Do not set these bind addresses to 0.0.0.0 unless the host firewall restricts every infrastructure port.

Step 2: Start Infrastructure

Use docker-compose.infra.yml to start all containerizable infrastructure:

# Start all infrastructure services
docker compose -f docker-compose.infra.yml up -d

# Wait until all services are healthy
docker compose -f docker-compose.infra.yml up -d --wait

Included services:

Service	Port	Management UI
Nacos	127.0.0.1:8848	http://localhost:8848/nacos
MySQL	127.0.0.1:3306	—
Redis	127.0.0.1:6379	—
RabbitMQ	127.0.0.1:5672	http://localhost:15672
MinIO-A	127.0.0.1:9000	http://localhost:9001
MinIO-B	127.0.0.1:9010	http://localhost:9011
OTel Collector	127.0.0.1:4317/4318/8889	—
Jaeger	127.0.0.1:16686	http://localhost:16686

Verify status:

docker compose -f docker-compose.infra.yml ps

Step 3: Configure Nacos

Nacos serves as the configuration center. Application configs must be imported.

1. Open Nacos console: http://localhost:8848/nacos and sign in with the credentials configured for this environment. If the Nacos image initializes a built-in default account, rotate it before exposing the host beyond your workstation.
2. Create configurations:

Data ID	Group	Description
backend-web.yaml	DEFAULT_GROUP	Backend main config (DB, Redis, RabbitMQ connections)
platform-storage.yaml	DEFAULT_GROUP	Storage service config (S3 node list, encryption params)

Important

Sensitive credentials (DB password, Redis password, etc.) are stored in Nacos configurations, not in .env. The infrastructure credentials in .env are only used by docker-compose. platform-fisco reads blockchain node, contract, signer, and nonce-state settings from deployment environment variables (FISCO_* or BSN_*), not from a Nacos Data ID. Supply BSN_BESU_PRIVATE_KEY through the deployment secret manager rather than committing it to .env.

Step 4: FISCO BCOS Node

The FISCO BCOS blockchain node cannot be started via docker-compose and requires manual deployment on the server.

Quick Setup (Single Group, 4 Nodes)

# Download build_chain script
curl -#LO https://github.com/FISCO-BCOS/FISCO-BCOS/releases/download/v3.8.0/build_chain.sh
chmod +x build_chain.sh

# Generate 4-node chain (Air version)
bash build_chain.sh -l 127.0.0.1:4 -p 30300,20200

# Start all nodes
bash nodes/127.0.0.1/start_all.sh

Copy SDK Certificates

# Copy certificates to the FISCO service resource directory
cp nodes/127.0.0.1/sdk/* platform-fisco/src/main/resources/conf/

Deploy Smart Contracts

Use the guarded deployment script instead of activating addresses manually. The script uses the FISCO BCOS console, verifies the version-controlled artifact catalog, reconciles the getGroupInfo chain/group/crypto/VM tuple with the explicit EVM deployment target, and rebuilds both contracts' ECC/SM creation and deployed runtime artifacts with fixed FISCO solc 0.8.11+commit.6b4cc280 keccak256/sm3 compilers. Before each deployment it compares canonical ABI and decoded bytecode and rechecks chain/group. After deployment it fetches getGroupInfo and the structured transaction receipt in one Console session, requires explicit success status 0, and cross-checks transaction hash and contract address before using that receipt's block number. It then verifies the complete getCode runtime bytes before contractIdentity(), publishes a structured audit receipt, and atomically updates .env.

This script is intentionally limited to BLOCKCHAIN_ACTIVE=local-fisco. It rejects BSN FISCO/Besu activation before any Console query; those networks require their own reviewed provider deployment process.

Set the target identity and durable audit location in .env:

FISCO_CHAIN_ID=chain0
FISCO_GROUP_ID=group0
CONTRACT_DEPLOYMENT_RECEIPT_DIR=/var/lib/record-platform/contract-deployments

# Preview every phase without changing the console, chain, or .env
./scripts/contract-deploy.sh --dry-run --console-dir /opt/fisco/console

# Deploy and atomically activate Storage and Sharing
./scripts/contract-deploy.sh \
  --console-dir /opt/fisco/console \
  --env-file .env \
  --receipt-dir /var/lib/record-platform/contract-deployments

# Recheck the signed catalog independently
python3 tools/contracts/contract_fingerprint.py verify \
  --project-root . \
  --catalog platform-fisco/src/main/resources/contract-registry/artifacts.json

Successful activation writes FISCO_STORAGE_CONTRACT, FISCO_SHARING_CONTRACT, and each contract's complete FISCO_*_DEPLOYMENT_TX, FISCO_*_DEPLOYMENT_BLOCK, and FISCO_*_DEPLOYMENT_EFFECTIVE_AT triplet with one shared UTC effective time. Before activation it atomically publishes a record-platform-contract-deployment-receipt.v2 JSON receipt containing the catalog SHA-256, LOCAL_FISCO chain/group identity, per-contract receiptStatus=SUCCESS, and both contracts' public name/version/address/transaction/block evidence. Every tx/address/block value comes from one successful receipt. It never records RPC URLs, certificates, private keys, or tokens; historical v1 receipts remain audit records only.

Do not copy only one address, leave a triplet empty, or provide only part of it. Wrong chain/group, unsupported WASM/crypto combinations, missing/failed/ambiguous receipts, transaction/address/block mismatch, catalog identity mismatch, solc output drift, missing runtime code, runtime bytes that do not match the signed artifact for the actual ECC/SM variant, non-zero/reverted identity calls, response parsing errors, or receipt write failures leave the previous .env unchanged. Dry-run performs no Console call, does not generate an effective time or receipt, and does not modify files or chain state. The Console's contract2java.sh must support -v 0.8.11 and provide $HOME/.fisco/solc/0.8.11/{keccak256,sm3}/solc; any ABI, creation, or runtime mismatch is blocked before the first deployment transaction.

./scripts/env-check.sh --service contracts verifies only the required field shapes. Restart platform-fisco for the authoritative check: startup queries each receipt through the selected active-chain client, requires FISCO status 0 or Besu status 1, compares tx/address/block, and publishes no ACTIVE registry if RPC or any field fails. Existing environments with empty evidence must obtain the real receipts or redeploy; do not invent placeholders. For rollback, restore the prior reviewed catalog, both addresses, and both real triplets together, then restart. If either receipt is no longer provable on the configured chain/group, keep the service stopped and redeploy rather than bypassing validation.

Artifact upgrades are reviewed changes: update both Solidity source copies, signed ABI, ECC/SM creation/runtime bytecode, semantic version, lifecycle status, and catalog fingerprints together. Retain deprecated/revoked artifacts and deployment receipts needed by historical proofs and audits. See Blockchain Integration for upgrade and rollback rules and scripts/README.md for all script options.

INFO

For detailed node and console setup, see the FISCO BCOS Documentation. RecordPlatform contract activation must still use the guarded repository script above.

Step 5: Verify Environment

Run the environment pre-check script to validate all infrastructure at once:

./scripts/env-check.sh

The script checks 8 items:

#	Check	Validates
1	Nacos	Connectivity + config existence
2	MySQL	Connection + database existence
3	Redis	Authentication + PING
4	RabbitMQ	AMQP port + management API
5	FISCO BCOS	Node port connectivity
6	S3/MinIO	Health check + bucket existence
7	TLS Certificates	File existence + expiry
8	Contract Addresses	Format validation

Auto-fix mode (creates database, buckets, etc.):

./scripts/env-check.sh --fix

Check a single service:

./scripts/env-check.sh --service mysql

Step 6: Build and Start

Build

# 1. Install shared interfaces (first time or when dependencies change)
mvn -f platform-api/pom.xml clean install

# 2. Install the shared proof/verifier SDK required by backend-service
mvn -f platform-verifier/pom.xml -pl sdk -am clean install -DskipTests

# 3. Build backend
mvn -f platform-backend/pom.xml clean package -DskipTests

# 4. Build FISCO service
mvn -f platform-fisco/pom.xml clean package -DskipTests

# 5. Build storage service
mvn -f platform-storage/pom.xml clean package -DskipTests

# 6. Frontend
cd platform-frontend && pnpm install && pnpm build

Start

# Start all services with the management script
./scripts/start.sh start all

# Check service status
./scripts/start.sh status

Startup order: platform-storage → platform-fisco → platform-backend → frontend

Verify

# Backend health check
curl http://localhost:8000/record-platform/actuator/health

# Frontend dev server
cd platform-frontend && pnpm dev

Troubleshooting

Issue	Cause	Solution
Nacos fails to start	Insufficient memory	Ensure Docker has ≥ 4GB memory allocated
MySQL connection refused	Container not ready	docker compose -f docker-compose.infra.yml up -d --wait
Redis AUTH failed	Password mismatch	Check REDIS_PASSWORD in .env matches Nacos config
FISCO service hangs on startup	Node unreachable	SdkBeanConfig connects on init — ensure node is running
MinIO inaccessible	Port conflict	Check if ports 9000/9001 are already in use
Dubbo service discovery fails	Wrong DUBBO_HOST	Set DUBBO_HOST to host IP in Docker environments
env-check.sh deep checks skipped	CLI tools missing	Install mysql-client, redis-cli, aws, etc.