pnoker
bca6d7aedc
Set up an end-to-end documentation site so contributors and users have a unified, searchable, and publishable entry point for project docs. - Add mkdocs.yml: Chinese-first language, light/dark palette, tabbed navigation, indexed sections, glightbox for diagrams, and pymdownx.snippets so community pages can pull from root governance files (CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md) without duplicating content. - Add requirements-docs.txt pinning mkdocs-material and mkdocs-glightbox. - Build the docs/ skeleton: index, quickstart, guide, architecture, development, modules, community. Migrate the seven generic manuals from dc3/doc/ (QUICKSTART, ENVIRONMENT, LOGGING, TROUBLESHOOTING, MODULES, DRIVER-AUTHORING, TESTING) and rewire their cross-doc links. CHANGE.md, TITLE.md, and USAGE.md stay in dc3/doc/ because docker-ci.yml depends on them; the docs site references them via mkdocs snippets to keep a single source of truth. - Add .github/workflows/docs.yml that builds with --strict on push to release and deploys via actions/deploy-pages. - Rewrite dc3/doc/README.md as a migration pointer to the new site and to the three retained release-flow files. Verification: mkdocs build --strict passes locally; snippets render correctly; GitHub Pages already enabled in workflow mode via gh api.
2.6 KiB
Troubleshooting FAQ
Common local development and runtime issues in IoT DC3 and how to resolve them.
1. Maven build is slow
Cause: Parallelism not enabled / JVM heap too small.
Resolution: Already configured in this repo:
.mvn/maven.configcontains-T 1C.mvn/jvm.configcontains-Xms512m -Xmx1024m
If still slow, increase heap or reduce background CPU load.
2. Unsupported class file major version / Java version errors
Cause: Project requires JDK 21.
Resolution:
java -version
mvn -version
The build now enforces JDK 21 via maven-enforcer-plugin.
3. Ports already in use
Symptom: Application fails to start due to occupied ports (8000/8300/8400/8500/8600/9300/9400/9500).
Resolution: Override ports using environment variables or .env values.
Common overrides:
SERVER_PORTGRPC_SERVER_PORTDC3_GATEWAY_PORTDC3_AUTH_PORTDC3_MANAGER_PORTDC3_DATA_PORT
4. Database connection failures in dev
Cause: Postgres container not started / custom .env changed published ports.
Resolution:
make compose-ps STACK=db
make compose-file STACK=db
Confirm the published port matches the application config.
5. RabbitMQ connection failures
Cause: Container not ready / wrong virtual host or credentials.
Resolution: Wait until healthcheck passes, then restart dependent services.
make compose-logs STACK=db
6. Nacos discovery errors in pre/pro profile
Cause: Those profiles expect service discovery via Nacos.
Resolution: For local source debugging, prefer dev profile unless you intentionally test registry behavior.
7. Gateway returns 401/403
Cause: Request routed to authenticated endpoints without token.
Resolution: Call token APIs first (/api/v3/auth/token/...), then pass the token in subsequent requests.
8. Driver cannot register
Cause: Manager not running / gRPC target address misconfigured.
Resolution: Start services in recommended order: Gateway -> Auth -> Data -> Manager -> Driver.
9. Docker image build fails in Makefile
Cause: mvn package failed inside image build.
Resolution:
make package
make build
10. China registry variant used unexpectedly
Cause: REGISTRY was set to cn.
Resolution: Use REGISTRY=global for Docker Hub images.
make dev-db REGISTRY=global
11. Want faster debugging in one JVM
Use dc3-center-single to combine Auth/Manager/Data into one process.
java -jar dc3-center/dc3-center-single/target/dc3-center-single.jar