From 6d4942c0136f58721920c4ab9f5756cc72d71428 Mon Sep 17 00:00:00 2001
From: Khalim Conn-Kowlessar <kconnkowlessar@gmail.com>
Date: Sat, 25 Apr 2026 15:03:07 +0000
Subject: [PATCH] adding to dev container to create shared network on start up

---
 .devcontainer/backend/devcontainer.json |  1 +
 Makefile                                | 10 +++++++++-
 README.md                               | 21 +++++++++++++++++++++
 3 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/.devcontainer/backend/devcontainer.json b/.devcontainer/backend/devcontainer.json
index a9b7352a..ee37224f 100644
--- a/.devcontainer/backend/devcontainer.json
+++ b/.devcontainer/backend/devcontainer.json
@@ -4,6 +4,7 @@
   "service": "model-backend",
   "remoteUser": "vscode",
   "workspaceFolder": "/workspaces/model",
+  "initializeCommand": "docker network create shared-dev 2>/dev/null || true",
   "postStartCommand": "bash .devcontainer/backend/post-install.sh",
   "mounts": [
     "source=${localEnv:HOME},target=/workspaces/home,type=bind",
diff --git a/Makefile b/Makefile
index 00942acd..255e2abf 100644
--- a/Makefile
+++ b/Makefile
@@ -2,7 +2,7 @@
 
 PYTHON = python
 
-.PHONY: setup test lint typecheck check clean
+.PHONY: setup test lint typecheck check clean network-setup dev-setup
 
 # Install dev dependencies + tox
 setup:
@@ -28,3 +28,11 @@ check: lint typecheck test
 # Clean up tox environments
 clean:
 	rm -rf .tox
+
+# Create shared Docker network required by dev container (idempotent)
+network-setup:
+	docker network create shared-dev 2>/dev/null || true
+
+# First-time dev environment setup
+dev-setup: network-setup
+	@echo "Dev environment ready. Open the repo in VS Code and select 'Reopen in Container'."
diff --git a/README.md b/README.md
index b470e12c..0f88328a 100644
--- a/README.md
+++ b/README.md
@@ -8,6 +8,27 @@ The different folders in this repository relate to services
 that can be used independently, or can be imported and used as
 part of a larger application
 
+# Getting Started
+
+## Prerequisites
+
+- [Docker Desktop](https://www.docker.com/products/docker-desktop/)
+- [VS Code](https://code.visualstudio.com/) with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+
+## Dev Container Setup
+
+This repo uses a Docker Compose-based dev container. The `model-backend` service joins a `shared-dev` Docker network so it can communicate with other local services (e.g. a frontend container) running on your machine.
+
+**VS Code users:** The `initializeCommand` in `devcontainer.json` creates the `shared-dev` network automatically before the container starts. No manual step required — just open the repo and select **Reopen in Container**.
+
+**Non-VS Code / CI workflows:** Run the following once before starting the container:
+
+```commandline
+make dev-setup
+```
+
+This is idempotent and safe to re-run if the network already exists.
+
 # Folders
 
 ### backend/