Document shared-network deployment patterns

README.md

@@ -87,6 +87,73 @@ If your New API service is named differently, change `DOWNSTREAM_URL` accordingl
 DOWNSTREAM_URL=http://my-newapi:3000
 ```
 
+## Common New API Connection Patterns
+
+In practice, you may run New API in either of these two ways.
+
+### Pattern A: Production machine, New API in its own compose
+
+This is the recommended production arrangement.
+
+New API keeps its own compose project and typically joins:
+
+- `default`
+- `shared_network`
+
+That means New API can continue to use its own internal compose network for its own dependencies, while also exposing its service name to Sentinel through `shared_network`.
+
+Example New API compose fragment:
+
+```yaml
+services:
+  new-api:
+    image: your-new-api-image
+    networks:
+      - default
+      - shared_network
+
+networks:
+  shared_network:
+    external: true
+```
+
+With this setup, Sentinel still uses:
+
+```text
+DOWNSTREAM_URL=http://new-api:3000
+```
+
+### Pattern B: Test machine, New API started as a standalone container
+
+On a test machine, you may not use a second compose project at all. Instead, you can start a standalone New API container with `docker run`, as long as that container also joins `shared_network`.
+
+Example:
+
+```bash
+docker run -d \
+  --name new-api \
+  --network shared_network \
+  your-new-api-image
+```
+
+Important:
+
+- The container name or reachable hostname must match what Sentinel uses in `DOWNSTREAM_URL`.
+- If the container is not named `new-api`, then adjust `.env` accordingly.
+- The port in `DOWNSTREAM_URL` is still the New API container's internal listening port.
+
+Example:
+
+```text
+DOWNSTREAM_URL=http://new-api:3000
+```
+
+or, if your standalone container is named differently:
+
+```text
+DOWNSTREAM_URL=http://new-api-test:3000
+```
+
 ## Local Development
 
 ### Backend
@@ -166,6 +233,8 @@ Important:
 - `new-api` here is the **service name** that Sentinel will resolve on the shared network.
 - The port in `DOWNSTREAM_URL` must be the **container internal port**, not the host published port.
 - If New API already listens on `3000` inside the container, use `http://new-api:3000`.
+- On a production host, New API can keep both `default` and `shared_network` at the same time.
+- On a test host, you can skip a second compose project and use `docker run`, but the container must still join `shared_network`.
 
 ### 3. Prepare Sentinel environment