R2D2-Holocron/README.md

holocron

Short information about the project.

Provide here all valuable links for the project (Wiki, documents, endpoints).

Quickstart

Building in local developer environment

Uses public Docker Hub images (no IronBank/VPN required):

# Ensure Docker is running, then:
make up
# or: docker compose -f docker-compose.local.yml up --build -d

Endpoints:

• Proxy: http://localhost:7070
• Health: http://localhost:7070/health
• Keycloak: http://localhost:7070/auth
• Frontend (Cesium): http://localhost:3001
• WebSocket: ws://localhost:9002

Keycloak admin: adminkeycloak / adminkeycloak

make down   # stop
make logs   # view logs
make clean  # stop and remove volumes

Sample data (assets on the map):
The local stack includes a test-publisher service that sends sample assets (UAVs, ships, ground units) to MQTT every 2 seconds. After make up, open http://localhost:3001 and you should see moving assets on the globe. If the map says "awaiting assets data", wait a few seconds for the publisher to connect and send, or check make logs for the test-publisher container.

To run a sample publisher manually (e.g. from host while stack is up):

cd holocron-cesium/test-publisher && npm install && MQTT_BROKER=mqtt://localhost:1883 node publisher.js

Verify build (run when Docker is up):

./scripts/verify-build.sh

Troubleshooting:

• error during connect... EOF → Docker/OrbStack not running; start it and retry
• Keycloak build fails on quay.io → Check network/proxy; try docker pull quay.io/keycloak/keycloak:22.0.1 manually
• Port 7070 in use → Change PROXY_EXPOSED_PORT in docker-compose or stop the conflicting service

Configuration and API keys (MapTiler):
Copy .env.example to .env and set MAPTILER_KEY if you want satellite/terrain tiles. The repo includes a .env for local use (not committed; see below). Keys are never hardcoded in the app: the frontend loads config from the server’s /api/config at runtime.

For IL environments with IronBank access, use cicd/.env.local and run from cicd/:

cd cicd && docker compose up --build -d

Building in IH environments

How to build and run the software in the IHLC environment.

Configuration and secrets (why keys are not in the app)

Changes made to keep API keys secure:

Change	Why
No key in CesiumViewer.jsx	The MapTiler key was hardcoded in the frontend. Anyone with the bundle could see it. It’s removed so the client never contains secrets.
Config from server	The viewer calls GET /api/config at runtime. The server reads process.env.MAPTILER_KEY and returns { maptilerKey }. The key stays on the server and is only sent over the wire to the browser when the app loads.
Keys in .env	Secrets live in .env (project root). Docker Compose loads it via env_file: .env for the frontend service, so the server process gets MAPTILER_KEY without putting it in code or in the repo.
.env in .gitignore	So .env is never committed. Each developer or deployment uses their own .env (or env vars).
.env.example	Documents which variables exist (e.g. MAPTILER_KEY=). Safe to commit; no real values. Copy to .env and fill in.
Fallback when no key	If MAPTILER_KEY is unset, the app uses OpenStreetMap tiles (no key) so the map still works without any key.

Flow: .env → Compose injects into container → server’s process.env.MAPTILER_KEY → /api/config → frontend uses it for tiles. The key is never in source code.

Production: Set CORS_ORIGIN (comma-separated origins) and WS_PUBLIC_URL (public WebSocket URL) so the same frontend build can be used behind different proxies. See .env.example for optional variables.

Technical stack

Shortly describe the technical stack of the project.

Design system

UI styling follows the R2 / Farsight aesthetic. The canonical reference (palette, fonts, Fumadocs + Scalar themes) lives in .settings/style/; see docs/STYLE.md for how the project's apps map to it and which tokens are aligned vs. intentionally divergent.

Visible endpoints

Describe all exposed endpoints of the project.