mirror of
https://github.com/jcreek/OpenNetworkDiagram.git
synced 2026-07-12 18:43:44 +00:00
docs(#4): Update readme
This commit is contained in:
@@ -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**.
|
**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**
|
✅ **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**
|
✅ **Interactive network visualisation**
|
||||||
✅ **Simple file-based configuration**
|
✅ **Simple file-based configuration**
|
||||||
✅ **Lightweight Svelte**
|
✅ **Lightweight Svelte**
|
||||||
@@ -20,25 +20,41 @@ Use it to **document your home lab, office network, or cloud infrastructure** wi
|
|||||||
|
|
||||||
## **🚀 Quick Start (For Users)**
|
## **🚀 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
|
```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.
|
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.
|
- Docker runtime reads **`/data/network.json`** from the mounted volume.
|
||||||
- In this repo, the default file is **`static/data/network.json`**.
|
- In this repo, your editable file is **`data/network.json`** (gitignored).
|
||||||
- Update that file to change the diagram data.
|
- 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`
|
- 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**
|
## **🛠️ Project Structure**
|
||||||
|
|
||||||
```
|
```text
|
||||||
open-network-diagram/
|
open-network-diagram/
|
||||||
│ ├── src/ # Svelte components
|
├── src/ # Svelte app source
|
||||||
│ ├── package.json # Dependencies
|
├── static/data/network.json # Demo dataset (Netlify/demo)
|
||||||
│── Dockerfile # Docker setup
|
├── data/network.json.example # User data template (Docker)
|
||||||
│── .github/workflows/ # CI/CD pipelines
|
├── Dockerfile # Docker build/runtime
|
||||||
│── README.md # Documentation
|
├── 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**
|
### **Run Locally**
|
||||||
|
|
||||||
```bash
|
```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`.
|
- GitHub Actions workflow (`.github/workflows/docker.yml`) builds Docker on PRs.
|
||||||
- Pushes the latest image to **Docker Hub**.
|
- 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",
|
"role": "Hypervisor",
|
||||||
"operatingSystem": "Proxmox",
|
"operatingSystem": "Proxmox",
|
||||||
"software": {
|
"software": {
|
||||||
"vms": [
|
"vms": [{ "name": "OpnSense", "role": "Router", "ipAddress": "10.0.0.4" }]
|
||||||
{ "name": "OpnSense", "role": "Router", "ipAddress": "10.0.0.4" },
|
|
||||||
{ "name": "PiVPN", "role": "VPN Server", "ipAddress": "10.0.0.5" }
|
|
||||||
]
|
|
||||||
},
|
},
|
||||||
"hardware": {
|
"hardware": {
|
||||||
"cpu": "Intel N100",
|
"cpu": "Intel N100",
|
||||||
@@ -125,7 +150,8 @@ Define your network using **`network.json`**:
|
|||||||
"networkPorts": 4
|
"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)
|
**Author:** [Joshua Creek](https://github.com/jcreek)
|
||||||
**Project Repo:** [GitHub](https://github.com/jcreek/OpenNetworkDiagram)
|
**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**
|
|
||||||
|
|||||||
Reference in New Issue
Block a user