Troubleshooting

Scene Import Fails with No JSON found in scenes/*.zip

Either the Git LFS extension is not installed, or git lfs pull did not run, so the scene bundle is still a small LFS pointer file instead of the real binary.

Confirm that scenes/Showcase.zip is an actual scene archive or only a Git LFS pointer, then fix it:

$ file scenes/Showcase.zip
scenes/Showcase.zip: ASCII text          # should be "Zip archive data", not text

$ head -c 60 scenes/Showcase.zip
version https://git-lfs.github.com/spec/v1              # confirms it's an LFS pointer

$ sudo apt install git-lfs
$ git lfs install
$ git lfs pull
$ file scenes/Showcase.zip
scenes/Showcase.zip: Zip archive data, at least v2.0 to extract   # fixed

Then rerun:

./setup.sh

setup.sh Succeeds But SCENESCAPE_UI_URL or DASHBOARD_URL is Unreachable from the Browser

This is almost always host DNS or proxy configuration rather than a service problem.

Confirm that the stack is healthy and reachable locally:

docker compose ps
curl -k https://localhost/api/v1/database-ready

If those local checks succeed but the configured hostname in $PUBLIC_HOSTNAME is still not reachable, verify the host DNS mapping and machine IP address. Replace my-host.example.com with your $PUBLIC_HOSTNAME. Replace 10.1.2.50 with your machine’s IP.

Check 1 — stale DNS. getent hosts $PUBLIC_HOSTNAME must resolve to this machine’s own IP address (compare with hostname -I):

$ getent hosts my-host.example.com
10.1.2.200      my-host.example.com        # wrong — not this machine's IP

$ hostname -I
10.1.2.50 172.17.0.1 ...                   # this machine is actually 10.1.2.50

Fix by adding a corrected entry to /etc/hosts (needs sudo):

echo "10.1.2.50 my-host.example.com" | sudo tee -a /etc/hosts

Check 2 — request to hostname is sent to the corporate proxy instead of the Smart Building deployment. With HTTP_PROXY and HTTPS_PROXY set, requests to $PUBLIC_HOSTNAME can still be routed through the corporate proxy and time out with HTTP 504, even after DNS is fixed, because no_proxy lists only the raw IP and not the hostname or domain:

$ curl -sk -o /dev/null -w "%{http_code}\n" https://my-host.example.com/api/v1/database-ready
504                                                       # proxy can't reach the private IP

$ curl -sk --noproxy '*' -o /dev/null -w "%{http_code}\n" https://my-host.example.com/api/v1/database-ready
200                                                       # works once the proxy is bypassed — confirms the proxy is the cause

Add the internal domain to no_proxy and NO_PROXY, for example .example.com, and check that nothing later in ~/.bashrc or other shell startup files re-exports no_proxy or NO_PROXY without it, because a later export no_proxy=... silently overwrites rather than appends to an earlier one. Restart the browser afterward so it picks up the change.