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**.
|
||||
|
||||
✅ **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**
|
||||
|
||||
Reference in New Issue
Block a user