Troubleshooting

The page does not respond

1. Check the port: 2502 for Docker, 2499 for Vite.
2. Inspect the container:

docker compose ps
docker compose logs --tail 100 astroguide

3. The health check requests http://127.0.0.1:2502/ inside the container. A failed health check points to Nginx, not your browser.

Black screen or missing 3D scene

• WebGL must be available;
• an aggressive content blocker can break modules;
• rendering intentionally stops outside the 3D view, so return to 3D exploration.

The THREE.Clock console warning is known and is not a failure by itself.

docker compose up fails

• host port already in use: change only the left-hand host port and keep the project port on the right;
• missing lockfile or npm ci --include=optional during a local build;
• insufficient permission to run Docker.

The demo has no welcome screen

You are probably running the normal product (npm run dev or the GHCR image). The badge and welcome screen only exist in dev:demo and build:demo.

Checkout quality

npm run check
npm audit --audit-level=high