Validate first-time install on an independent machine

[josedaniel-dev]

Goal

Have a person who did not develop Observer follow the public documentation from a clean machine and report whether the first trace is visible without undocumented steps.

Safety

Use only synthetic prompts and identifiers. Do not attach environment dumps, credentials, private URLs, or real telemetry to this issue.

Checklist

• Use a clean Linux VM, container host, or machine without an existing Observer checkout or Python/Node environment
• Follow the README Docker Compose quickstart literally
• Confirm the backend health endpoint reports a healthy database
• Open the dashboard and confirm it loads without an API error
• Send the documented synthetic trace and confirm it appears in the Traces view
• Install @magic-lab-studio/observer from npm in a new project and run one synthetic SDK trace
• After the Python packages are published, install magic-lab-observer and magic-lab-observer-cli from PyPI in a new virtual environment
• Record OS/runtime versions, total setup time, every documentation deviation, and sanitized error text

Pass criteria

A new user can reach a visible synthetic trace by following public documentation only. Any missing command, ambiguous prerequisite, or hidden local assumption produces a documentation follow-up before closing this issue.

[josedaniel-dev]

Automated baseline completed for Observer 0.1.1:

• Clean Ubuntu Compose smoke passed, including browser-to-API rendering of a synthetic trace.
• All three Python distributions installed together from PyPI in a new Python 3.13 virtual environment; SDK/backend imports and the CLI entrypoint passed.
• The TypeScript SDK installed from npm in a new project and imported successfully.
• Public package metadata points to this repository and declares Apache-2.0.

The remaining acceptance criterion is intentionally human: a person who did not develop Observer should follow the README without assistance and record any undocumented step.

[josedaniel-dev]

Automated independent-install validation repeated on 2026-08-08 against main commit 7b64585, using only synthetic data.

Environment and timing:

• fresh single-branch clone with no local Node/Python dependencies
• clean Linux Docker-in-Docker host: Docker 29.7.1
• outer host: Windows/Docker Desktop; the isolated host exposed Observer externally on 18000/15173/15432 to avoid unrelated host services, while the repository Compose file was run unchanged
• clean docker compose up -d: PASS in 8m13s, including fresh image downloads/builds

Results:

• PostgreSQL: healthy
• GET /health: {"status":"healthy","db":"ok","version":"0.1.1"}
• documented synthetic HTTP trace demo-support-session: ingested and returned by GET /v1/traces
• dashboard root: HTTP 200
• the dashboard's exact traces request, GET /api/v1/traces/: HTTP 200 JSON and includes the synthetic traces
• @magic-lab-studio/observer@0.1.1: installed in a new npm project with 0 vulnerabilities; exported npm-sdk-synthetic, confirmed through the API
• Python 3.13 virtualenv: magic-lab-observer==0.1.1, magic-lab-observer-cli==0.1.1, and magic-lab-observer-backend==0.1.1 installed
• Python SDK import and CLI entrypoint: PASS
• Python SDK exported python-sdk-synthetic, confirmed through the API

Documentation deviation found:

• the documented plain backend install imports the default SQLite configuration without installing aiosqlite
• magic-lab-observer-backend[sqlite]==0.1.1 fixes the import
• documentation correction is included in draft PR fix(release): clear dependency audit gate #24

Release-gate fix:

• PR fix(release): clear dependency audit gate #24 upgrades React Router to 7.18.2
• official manually dispatched Dependency audit run 31272763120: PASS for dashboard and TypeScript SDK
• all PR CI checks currently pass

This remains an automated validation. The issue's intentionally human criterion — a person who did not develop Observer following the README and visually confirming the Traces view — is still pending, so I am leaving #20 open.