docs(#4): Update readme

This commit is contained in:
Josh Creek
2026-02-22 16:57:25 +00:00
parent e002764e32
commit 824db1c005
+51 -33
View File
@@ -9,7 +9,7 @@
**Open Network Diagram** is an **open-source, self-hosted tool** for creating **interactive network and infrastructure diagrams** using a **declarative JSON format**.
**Fully self-hostable via Docker**
**JSON-based network structure** (editable in UI or manually)
**Docker-first deployment target** (Netlify optional for demo hosting)
**Interactive network visualisation**
**Simple file-based configuration**
**Lightweight Svelte**
@@ -20,25 +20,41 @@ Use it to **document your home lab, office network, or cloud infrastructure** wi
## **🚀 Quick Start (For Users)**
### **1️⃣ Run Open Network Diagram via Docker**
### **1️⃣ Create Your Runtime Data File**
Pull and run the latest image:
Copy the template and edit your own network data:
```bash
docker run -d -p 8080:3000 jcreek23/open-network-diagram
cp data/network.json.example data/network.json
```
- **`-p 8080:3000`** → Maps the app to `http://localhost:8080`
### **2️⃣ Run Open Network Diagram via Docker**
### **2️⃣ Open the Web UI**
From this repo:
```bash
docker compose up --build
```
Or pull and run directly:
```bash
docker run -d -p 8080:80 -v "$(pwd)/data:/usr/share/nginx/html/data:ro" jcreek23/open-network-diagram
```
- **`-p 8080:80`** → Maps the app to `http://localhost:8080`
- **`-v .../data:/usr/share/nginx/html/data:ro`** → Uses your local `data/network.json`
### **3️⃣ Open the Web UI**
Visit **`http://localhost:8080`** to view your network diagram.
### **3️⃣ Modify Your Network (JSON-Based)**
### **4️⃣ Modify Your Network (JSON-Based)**
- The app reads **`/data/network.json`** from static assets.
- In this repo, the default file is **`static/data/network.json`**.
- Update that file to change the diagram data.
- Docker runtime reads **`/data/network.json`** from the mounted volume.
- In this repo, your editable file is **`data/network.json`** (gitignored).
- Netlify demo builds use committed sample data at **`static/data/network.json`**.
- After editing JSON, click **Reload Default JSON** in the UI.
---
@@ -65,17 +81,28 @@ pnpm run dev
- Runs at `http://localhost:5173`
### **4️⃣ Build Targets**
```bash
pnpm run build # default (Docker/static target)
pnpm run build:docker # explicit Docker/static target
pnpm run build:netlify # explicit Netlify target
```
---
## **🛠️ Project Structure**
```
```text
open-network-diagram/
├── src/ # Svelte components
│ ├── package.json # Dependencies
── Dockerfile # Docker setup
── .github/workflows/ # CI/CD pipelines
── README.md # Documentation
├── src/ # Svelte app source
├── static/data/network.json # Demo dataset (Netlify/demo)
── data/network.json.example # User data template (Docker)
── Dockerfile # Docker build/runtime
── docker-compose.yml # Local Docker run with mounted data
├── netlify.toml # Netlify build config
├── .github/workflows/ # CI workflows (Docker image build/push)
└── README.md # Documentation
```
---
@@ -91,13 +118,14 @@ docker build -t open-network-diagram .
### **Run Locally**
```bash
docker run -p 8080:3000 open-network-diagram
docker run --rm -p 8080:80 -v "$(pwd)/data:/usr/share/nginx/html/data:ro" open-network-diagram
```
### **CI/CD (GitHub Actions)**
### **CI/CD (GitHub Actions + Netlify)**
- Automatic Docker builds when changes are pushed to `main`.
- Pushes the latest image to **Docker Hub**.
- GitHub Actions workflow (`.github/workflows/docker.yml`) builds Docker on PRs.
- Pushes to `main` publish Docker images to **Docker Hub** (`jcreek23/open-network-diagram`).
- Netlify uses its own CI/CD pipeline with `netlify.toml` (`pnpm run build:netlify`).
---
@@ -114,10 +142,7 @@ Define your network using **`network.json`**:
"role": "Hypervisor",
"operatingSystem": "Proxmox",
"software": {
"vms": [
{ "name": "OpnSense", "role": "Router", "ipAddress": "10.0.0.4" },
{ "name": "PiVPN", "role": "VPN Server", "ipAddress": "10.0.0.5" }
]
"vms": [{ "name": "OpnSense", "role": "Router", "ipAddress": "10.0.0.4" }]
},
"hardware": {
"cpu": "Intel N100",
@@ -125,7 +150,8 @@ Define your network using **`network.json`**:
"networkPorts": 4
}
}
]
],
"devices": [{ "name": "Switch", "ipAddress": "10.0.0.2", "type": "Nintendo Switch" }]
}
```
@@ -163,11 +189,3 @@ We welcome contributions! To contribute:
**Author:** [Joshua Creek](https://github.com/jcreek)
**Project Repo:** [GitHub](https://github.com/jcreek/OpenNetworkDiagram)
---
### **🔥 Next Steps**
**Set up GitHub Repo**
**Push initial project structure**
**Add CI/CD for automated Docker builds**