Quick start for the inner-loop demo; fix its PV-write smoke test; refresh integration README

README.md

@@ -12,6 +12,18 @@ simulated IOC, wired together for a local backend inner loop via
 `docker compose`. The React/Vite frontend lives here too but is run
 separately (see below).
 
+## Quick start
+
+1. `git clone https://github.com/NSLS2/ophyd-service.git`
+2. `cd ophyd-service`
+3. `docker compose up -d --build`
+4. Open the interactive API docs:
+   http://localhost:8004/docs (configuration_service) and
+   http://localhost:8003/docs (direct_control_service)
+5. When done: `docker compose down`
+
+Everything below is detail on what that stack is and how to work with it.
+
 ## Layout
 
 | Path | Role |
@@ -144,6 +156,12 @@ Both backends expose Swagger UI:
   `sqlite+pysqlite:////var/lib/config_service/config.db`). PostgreSQL is
   recommended for production / multi-writer deploys; SQLite suits single-node /
   dev use. This compose stack uses the bundled `postgres` service.
+- **`shared-schema/` must be writable by container uid 1000.** Both backends
+  export their live OpenAPI schema into the bind-mounted directory at startup
+  and fail hard (exit) if the write is denied. On a checkout owned by a
+  different uid, grant that uid access first — `sudo chown -R 1000 shared-schema`,
+  or `setfacl -R -m u:1000:rwX shared-schema` to leave ownership untouched — or
+  unset `OPHYD_SERVICE_OPENAPI_EXPORT_PATH` to skip the export.
 - Startup happi-seeding (`CONFIG_LOAD_STRATEGY=happi`) is the dev shortcut here.
   Production deployments seed the registry via profile files or CRUD calls from
   an upstream Experiment Execution Service.

docker-compose.yml

@@ -86,6 +86,12 @@ services:
       DIRECT_CONTROL_CONFIGURATION_SERVICE_URL: http://configuration_service:8004
       # Skip the coordination check — no EE service running in compose.
       DIRECT_CONTROL_COORDINATION_CHECK_ENABLED: "false"
+      # The service defaults to read-only until an operator opts in to writes.
+      # This stack only talks to the simulated IOC, so enable them — the same
+      # choice every integration pod makes. Writes cannot reach real hardware:
+      # EPICS_CA_ADDR_LIST below pins CA to the compose-network IOC and
+      # auto-addr is off, so nothing outside this stack is addressable.
+      DIRECT_CONTROL_GLOBAL_READ_ONLY: "false"
       # pyepics reads these. Point it at the compose-network IOC; disable
       # auto-addr so it doesn't broadcast on the host network.
       EPICS_CA_ADDR_LIST: ioc