11 Commits

Author SHA1 Message Date
Josh Creek 808fe5a440 Merge pull request #15 from jcreek/14-read-only-mode
fix(#14): surface explicit writable diagnostics in API and read-only …
2026-03-05 19:00:30 +00:00
Josh Creek c2bffede3e fix(#14): surface explicit writable diagnostics in API and read-only banner 2026-03-05 18:51:04 +00:00
Josh Creek a09c98ec46 build(*): Use correct token 2026-02-25 23:59:10 +00:00
Josh Creek 129041368b build(*): Attempt to diagnose dockerhub action issue 2026-02-25 23:56:47 +00:00
Josh Creek 3615c38794 docs(*): Change wording 2026-02-25 23:46:25 +00:00
Josh Creek 3ce0adfa0b Merge pull request #9 from jcreek/dependabot/github_actions/peter-evans/dockerhub-description-5
build(deps): bump peter-evans/dockerhub-description from 4 to 5
2026-02-25 23:44:15 +00:00
Josh Creek a7dbcf426f build(*): Ensure dockerhub updates overview not short description 2026-02-25 23:42:40 +00:00
dependabot[bot] b1fb4fc141 build(deps): bump peter-evans/dockerhub-description from 4 to 5
Bumps [peter-evans/dockerhub-description](https://github.com/peter-evans/dockerhub-description) from 4 to 5.
- [Release notes](https://github.com/peter-evans/dockerhub-description/releases)
- [Commits](https://github.com/peter-evans/dockerhub-description/compare/v4...v5)

---
updated-dependencies:
- dependency-name: peter-evans/dockerhub-description
  dependency-version: '5'
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
2026-02-25 23:39:21 +00:00
Josh Creek 1d656ff120 build(*): Set up docker repository overview syncing from readme 2026-02-25 23:38:43 +00:00
Josh Creek 45203a4c28 feat(*): Enhance example network json 2026-02-25 23:27:16 +00:00
Josh Creek 4cbec53394 docs(*): Improve readme 2026-02-25 23:24:30 +00:00
13 changed files with 545 additions and 295 deletions
+6
View File
@@ -0,0 +1,6 @@
version: 2
updates:
- package-ecosystem: github-actions
directory: /
schedule:
interval: weekly
@@ -0,0 +1,59 @@
name: Docker Hub Description
on:
push:
branches:
- main
paths:
- README.md
- .github/workflows/dockerhub-description.yml
jobs:
dockerhub-description:
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Preflight Docker Hub repository access
env:
DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
DOCKERHUB_PASSWORD: ${{ secrets.DOCKERHUB_TOKEN }}
DOCKERHUB_REPOSITORY: jcreek23/open-network-diagram
run: |
set -euo pipefail
if [ -z "${DOCKERHUB_USERNAME}" ] || [ -z "${DOCKERHUB_PASSWORD}" ]; then
echo "Missing DOCKERHUB_USERNAME or DOCKERHUB_PASSWORD secret."
exit 1
fi
LOGIN_RESPONSE="$(curl -fsS -X POST \
-H 'Content-Type: application/json' \
-d "{\"username\":\"${DOCKERHUB_USERNAME}\",\"password\":\"${DOCKERHUB_PASSWORD}\"}" \
https://hub.docker.com/v2/users/login/)"
TOKEN="$(printf '%s' "${LOGIN_RESPONSE}" | ruby -rjson -e 'input = STDIN.read; data = JSON.parse(input); puts data.fetch("token", "")')"
if [ -z "${TOKEN}" ]; then
echo "Docker Hub login succeeded but token was missing."
exit 1
fi
curl -fsS \
-H "Authorization: JWT ${TOKEN}" \
"https://hub.docker.com/v2/repositories/${DOCKERHUB_REPOSITORY}/" >/dev/null
echo "Docker Hub preflight access check passed for ${DOCKERHUB_REPOSITORY}."
- name: Update Docker Hub repository overview
uses: peter-evans/dockerhub-description@v5
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
repository: jcreek23/open-network-diagram
readme-filepath: ./README.md
enable-url-completion: true
+1 -1
View File
@@ -38,7 +38,7 @@ jobs:
- name: Create Git tag + GitHub release
id: semantic
uses: cycjimmy/semantic-release-action@v5.0.2
uses: cycjimmy/semantic-release-action@v5
with:
extra_plugins: |
@semantic-release/commit-analyzer
+125 -145
View File
@@ -1,177 +1,147 @@
# **Open Network Diagram**
# Open Network Diagram
![Docker Pulls](https://img.shields.io/docker/pulls/jcreek23/open-network-diagram)
![Release Workflow](https://img.shields.io/github/actions/workflow/status/jcreek/OpenNetworkDiagram/release.yml?branch=main&label=release)
![Docker CI Workflow](https://img.shields.io/github/actions/workflow/status/jcreek/OpenNetworkDiagram/docker.yml?label=docker%20ci)
![Latest Release](https://img.shields.io/github/v/release/jcreek/OpenNetworkDiagram?display_name=tag&sort=semver)
![Netlify](https://img.shields.io/netlify/3128f05f-831b-412c-ada0-46bc3d6e61d5)
[![Docker Pulls](https://img.shields.io/docker/pulls/jcreek23/open-network-diagram)](https://hub.docker.com/r/jcreek23/open-network-diagram)
[![Release Workflow](https://img.shields.io/github/actions/workflow/status/jcreek/OpenNetworkDiagram/release.yml?branch=main&label=release)](https://github.com/jcreek/OpenNetworkDiagram/actions/workflows/release.yml)
[![Docker CI Workflow](https://img.shields.io/github/actions/workflow/status/jcreek/OpenNetworkDiagram/docker.yml?label=docker%20ci)](https://github.com/jcreek/OpenNetworkDiagram/actions/workflows/docker.yml)
[![Latest Release](https://img.shields.io/github/v/release/jcreek/OpenNetworkDiagram?display_name=tag&sort=semver)](https://github.com/jcreek/OpenNetworkDiagram/releases)
[![Netlify](https://img.shields.io/netlify/3128f05f-831b-412c-ada0-46bc3d6e61d5)](https://opennetworkdiagram.jcreek.co.uk)
**A declarative, self-hosted tool for visualising and managing home lab & network architecture diagrams.**
**A declarative, self-hosted containerised tool for visualising and managing home lab & network architecture diagrams.**
---
Open Network Diagram helps you document your infrastructure in a visual UI while keeping a real JSON source of truth you can version, back up, and reuse.
## **📝 About**
- Homelab-friendly: run it in minutes with Docker.
- Practical: edit in the UI and autosave to `network.json`.
- Declarative: keep your topology in Git if you wish.
**Open Network Diagram** is an **open-source, self-hosted tool** for creating **interactive network and infrastructure diagrams** using a **declarative JSON format**.
[Docker Hub](https://hub.docker.com/r/jcreek23/open-network-diagram) | [Live Demo (Read-Only)](https://opennetworkdiagram.jcreek.co.uk) | [GitHub Releases](https://github.com/jcreek/OpenNetworkDiagram/releases)
**Fully self-hostable via Docker**
**Docker-first deployment target** (Netlify optional for demo hosting)
**Interactive network visualisation**
**Single-page modal editor with live updates**
**Debounced autosave to JSON (self-hosted)**
**Local vendored icon catalog (offline runtime)**
**Lightweight Svelte**
![Open Network Diagram network view with ethernet labels](screenshot1.png)
Use it to **document your home lab, office network, or cloud infrastructure** with an easy-to-use web interface.
## Features
---
- Network view with ethernet labels to make physical and logical links easy to read.
- Non-network view for host-first inventory and service mapping.
- Expandable VM lists per machine for quick virtualization visibility.
- Modal editor for machines/devices with live diagram updates.
- JSON-backed persistence with autosave in self-hosted mode.
- Docker-first deployment with writable data volume support.
- Optional read-only mode for public demos and safe sharing.
- Local vendored icon catalog for offline-friendly runtime behavior.
## **🚀 Quick Start (For Users)**
## Why Home Lab Users Use It
### **1️⃣ Create Your Runtime Data File**
- Keep an always-up-to-date map of machines, VMs, and devices.
- Edit quickly through a modal UI instead of hand-editing large diagrams.
- Persist everything to JSON so backups and Git workflows stay simple.
- Stay fully self-hosted with no runtime dependency on external APIs.
Copy the template and edit your own network data:
## 2-Minute Docker Quick Start
This is the fastest way to run Open Network Diagram for a home lab.
1. Create a local data folder and seed your first `network.json`:
```bash
cp data/network.json.example data/network.json
mkdir -p ond-data
curl -fsSL https://raw.githubusercontent.com/jcreek/OpenNetworkDiagram/main/data/network.json.example -o ond-data/network.json
```
### **2️⃣ Run Open Network Diagram via Docker**
From this repo:
2. Run the published Docker image:
```bash
docker compose up --build
```
Or pull and run directly:
```bash
docker run -d -p 8080:3000 \
docker run -d \
--name open-network-diagram \
--restart unless-stopped \
-p 8080:3000 \
-e NETWORK_DATA_FILE=/app/data/network.json \
-e NETWORK_BACKUP_DIR=/app/data/.backups \
-v "$(pwd)/data:/app/data" \
jcreek23/open-network-diagram
-v "$(pwd)/ond-data:/app/data" \
jcreek23/open-network-diagram:latest
```
- **`-p 8080:3000`** → Maps the app to `http://localhost:8080`
- **`-v .../data:/app/data`** → Uses your local writable `data/network.json`
3. Open the app at `http://localhost:8080`.
### **3️⃣ Open the Web UI**
4. Edit your topology in the UI. Changes persist to `ond-data/network.json`.
Visit **`http://localhost:8080`** to view your network diagram.
Useful follow-up commands:
### **4️⃣ Modify Your Network (Modal UI + JSON Persistence)**
```bash
docker logs -f open-network-diagram
docker stop open-network-diagram
docker rm open-network-diagram
```
- Edit machines/devices/VMs/ports directly in the modal UI.
- Diagram updates immediately as you edit.
- In self-hosted Docker/local mode, changes autosave to mounted **`data/network.json`**.
- Netlify/demo is intentionally read-only; edits are in-memory only.
## What It Looks Like
---
| Network view with ethernet labels | Non-network view with VMs expanded | Modal editing a machine |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| ![Open Network Diagram network view with ethernet labels](screenshot1.png) | ![Open Network Diagram non-network view with VMs expanded](screenshot2.png) | ![Open Network Diagram modal editing a machine](screenshot3.png) |
## **👩‍💻 Development Setup**
## Docker Compose Option
### **1️⃣ Clone the Repository**
If you prefer compose:
```yaml
services:
open-network-diagram:
image: jcreek23/open-network-diagram:latest
ports:
- '8080:3000'
volumes:
- ./ond-data:/app/data
environment:
NETWORK_DATA_FILE: /app/data/network.json
NETWORK_BACKUP_DIR: /app/data/.backups
restart: unless-stopped
```
Start it with:
```bash
docker compose up -d
```
## For Developers
### Local Development
```bash
git clone https://github.com/jcreek/OpenNetworkDiagram.git
cd open-network-diagram
```
### **2️⃣ Install Dependencies**
```bash
cd OpenNetworkDiagram
pnpm install
```
### **3️⃣ Run in Development Mode**
```bash
pnpm run dev
```
- Runs at `http://localhost:5173`
App URL: `http://localhost:5173`
### **4️⃣ Build Targets**
### Build Targets
```bash
pnpm run build # default (Docker/static target)
pnpm run build:docker # explicit Docker/static target
pnpm run build # default build
pnpm run build:docker # Docker/static target
pnpm run build:netlify # Netlify target (read-only mode)
pnpm run icons:manifest # regenerate local vendor icon manifest
```
---
### Runtime and Persistence
## **🛠️ Project Structure**
- API endpoint: `GET/PUT /api/network-data`
- Writes are enabled unless `NETWORK_READ_ONLY=true`
- When writes are unavailable, API responses include `writableReason` for diagnostics.
- Writes are persisted atomically to the configured data file
- Rolling backups are kept in the backup directory (last 5)
```text
open-network-diagram/
├── src/ # Svelte app source
├── src/lib/config/vendorIconManifest.ts # Generated local icon catalog
├── static/data/network.json # Demo dataset (Netlify/demo)
├── static/icons/vendor/ # Vendored icon assets (runtime-local)
├── data/network.json.example # User data template (Docker)
├── third_party/ # Third-party license/provenance notes
├── Dockerfile # Docker build/runtime
├── server.mjs # Node runtime server (static + /api/network-data)
├── docker-compose.yml # Local Docker run with mounted data
├── netlify.toml # Netlify build config
├── .github/workflows/ # CI workflows (PR build + automated release/publish)
└── README.md # Documentation
```
Environment variables:
---
- `NETWORK_READ_ONLY` (default: `false`)
- Set to `true` to disable writes and force read-only mode.
- `NETWORK_DATA_FILE` (default: `data/network.json`)
- JSON file path to read/write.
- `NETWORK_BACKUP_DIR` (default: `data/.backups`)
- Directory for backup files.
## **📦 Docker Build & Deployment**
### **Build the Docker Image Locally**
```bash
docker build -t open-network-diagram .
```
### **Run Locally**
```bash
docker run --rm -p 8080:3000 \
-e NETWORK_DATA_FILE=/app/data/network.json \
-e NETWORK_BACKUP_DIR=/app/data/.backups \
-v "$(pwd)/data:/app/data" \
open-network-diagram
```
### **Write API Environment Variables**
- **`NETWORK_READ_ONLY`** (default: `false`)
Set to `true` to disable `PUT /api/network-data` and force read-only mode.
- **`NETWORK_DATA_FILE`** (default: `data/network.json`)
JSON file path to read/write.
- **`NETWORK_BACKUP_DIR`** (default: sibling `.backups`)
Backup directory for rolling save backups (last 5 retained).
### **Local Icon Catalog (No Runtime Network Dependency)**
- Icons are vendored locally under **`static/icons/vendor/homarr/`**.
- The searchable catalog is generated into **`src/lib/config/vendorIconManifest.ts`**.
- Third-party provenance and licensing are documented in:
- **`third_party/homarr-dashboard-icons/SOURCE.txt`**
- **`third_party/homarr-dashboard-icons/LICENSE`**
- **`third_party/homarr-dashboard-icons/NOTICE.txt`**
- Runtime icon search/rendering does not call external APIs.
### **CI/CD (GitHub Actions + Netlify)**
- GitHub Actions workflow (`.github/workflows/docker.yml`) builds Docker on PRs (validation only).
- GitHub Actions workflow (`.github/workflows/release.yml`) runs on `main`, creates semantic version tags/releases, and publishes Docker images to **Docker Hub** (`jcreek23/open-network-diagram`).
- Netlify uses its own CI/CD pipeline with `netlify.toml` (`pnpm run build:netlify`).
---
## **📝 JSON Network Configuration Example**
Define your network using **`network.json`**:
### JSON Example
```json
{
@@ -195,27 +165,37 @@ Define your network using **`network.json`**:
}
```
---
### Project Structure
## **🤝 Contributing**
```text
OpenNetworkDiagram/
├── src/ # Svelte app source
├── src/lib/config/vendorIconManifest.ts # Generated local icon catalog
├── static/data/network.json # Demo dataset (Netlify)
├── static/icons/vendor/ # Vendored icon assets (runtime-local)
├── data/network.json.example # Starter data template for Docker users
├── third_party/ # Third-party provenance + licensing
├── Dockerfile # Docker build/runtime image
├── server.mjs # Node runtime server (static + API)
├── docker-compose.yml # Local compose example (build from repo)
├── netlify.toml # Netlify build config
└── .github/workflows/ # CI workflows
```
We welcome contributions! To contribute:
### CI/CD
1. **Fork the repository**.
2. **Create a feature branch** (`git checkout -b feature-name`).
3. **Commit your changes** (`git commit -m "Add feature X"`).
4. **Push to your fork** (`git push origin feature-name`).
5. **Submit a Pull Request**.
- `docker.yml`: validates Docker build on pull requests.
- `release.yml`: semantic release on `main` and Docker Hub publish for tagged releases.
- Docker Hub image: [`jcreek23/open-network-diagram`](https://hub.docker.com/r/jcreek23/open-network-diagram)
---
## Contributing
## **📜 License**
1. Fork the repository.
2. Create a feature branch.
3. Commit your changes.
4. Push your branch.
5. Open a pull request.
[GNU GPL v3 License](LICENSE) Free to use, modify, and distribute, except distributing closed source versions.
## License
---
## **📬 Contact**
**Author:** [Joshua Creek](https://github.com/jcreek)
**Project Repo:** [GitHub](https://github.com/jcreek/OpenNetworkDiagram)
[GNU GPL v3](LICENSE)
BIN
View File
Binary file not shown.

After

Width:  |  Height:  |  Size: 276 KiB

BIN
View File
Binary file not shown.

After

Width:  |  Height:  |  Size: 334 KiB

BIN
View File
Binary file not shown.

After

Width:  |  Height:  |  Size: 274 KiB

+19 -9
View File
@@ -4,8 +4,7 @@ import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { validateNetworkData } from './src/lib/shared/networkSchemaCore.mjs';
import {
checkWritableState,
isWriteEnabled,
getWritableState,
readNetworkFile,
writeNetworkFile
} from './src/lib/shared/networkPersistenceCore.mjs';
@@ -50,10 +49,17 @@ function badRequest(response, message, details) {
});
}
function resolveReadOnlyErrorMessage(reason) {
if (!reason) {
return 'Write API unavailable in current deployment.';
}
return `Write API unavailable: ${reason}`;
}
async function serveApi(request, response) {
if (request.method === 'GET') {
try {
const payload = await readNetworkFile();
const [payload, writableState] = await Promise.all([readNetworkFile(), getWritableState()]);
const validation = validateNetworkData(payload.data);
if (!validation.valid) {
sendJson(response, 500, {
@@ -63,11 +69,10 @@ async function serveApi(request, response) {
return;
}
const canWrite = await checkWritableState();
sendJson(response, 200, {
data: validation.data,
writable: canWrite,
writable: writableState.writable,
writableReason: writableState.reason,
source: payload.source,
updatedAt: payload.updatedAt
});
@@ -80,9 +85,12 @@ async function serveApi(request, response) {
}
if (request.method === 'PUT') {
if (!isWriteEnabled()) {
const writableStateBeforeWrite = await getWritableState();
if (!writableStateBeforeWrite.writable) {
sendJson(response, 403, {
error: 'Write API disabled. Unset NETWORK_READ_ONLY to enable persistence.'
error: resolveReadOnlyErrorMessage(writableStateBeforeWrite.reason),
writable: false,
writableReason: writableStateBeforeWrite.reason
});
return;
}
@@ -123,9 +131,11 @@ async function serveApi(request, response) {
try {
const metadata = await writeNetworkFile(validation.data);
const writableStateAfterWrite = await getWritableState();
sendJson(response, 200, {
data: validation.data,
writable: true,
writable: writableStateAfterWrite.writable,
writableReason: writableStateAfterWrite.reason,
source: metadata.source,
updatedAt: metadata.updatedAt
});
+23 -2
View File
@@ -73,7 +73,8 @@
let saveState: SaveState = 'saved';
let dataSourceLabel = jsonPath;
let writable = false;
let readOnlyNotice = 'Read-only deployment; changes are not persisted.';
const defaultReadOnlyNotice = 'Read-only deployment; changes are not persisted.';
let readOnlyNotice = defaultReadOnlyNotice;
let showEthernetLabels = false;
let diagramViewMode: DiagramViewMode = 'network';
@@ -401,6 +402,13 @@
return 'Unexpected error';
}
function resolveReadOnlyNotice(reason: string | null | undefined): string {
if (!reason) {
return defaultReadOnlyNotice;
}
return `Read-only: ${reason}`;
}
function createGraphStyles(theme: ThemeMode): cytoscape.Stylesheet[] {
const nodeText = theme === 'dark' ? '#e2e8f0' : '#1e293b';
const textOutline = theme === 'dark' ? '#0f172a' : '#f8fafc';
@@ -976,8 +984,12 @@
});
if (response.status === 403) {
const body = (await response.json().catch(() => ({}))) as {
error?: string;
writableReason?: string | null;
};
writable = false;
readOnlyNotice = 'Read-only deployment; changes are not persisted.';
readOnlyNotice = resolveReadOnlyNotice(body.writableReason ?? body.error ?? null);
saveState = 'unsaved';
return;
}
@@ -998,10 +1010,14 @@
const body = (await response.json()) as {
data: NetworkData;
writable: boolean;
writableReason?: string | null;
source: string;
updatedAt: string;
};
writable = body.writable;
readOnlyNotice = body.writable
? defaultReadOnlyNotice
: resolveReadOnlyNotice(body.writableReason);
dataSourceLabel = body.source;
lastSavedSnapshot = JSON.stringify(body.data);
networkData = cloneNetworkData(body.data);
@@ -1385,6 +1401,7 @@
const body = (await response.json()) as {
data: NetworkData;
writable: boolean;
writableReason?: string | null;
source: string;
updatedAt: string;
};
@@ -1396,6 +1413,9 @@
networkData = cloneNetworkData(validation.data);
ensureSelectedTargetValid();
writable = body.writable;
readOnlyNotice = body.writable
? defaultReadOnlyNotice
: resolveReadOnlyNotice(body.writableReason);
dataSourceLabel = body.source;
lastSavedSnapshot = JSON.stringify(networkData);
saveState = 'saved';
@@ -1414,6 +1434,7 @@
networkData = cloneNetworkData(fallbackData);
ensureSelectedTargetValid();
writable = false;
readOnlyNotice = 'Read-only: API unavailable; using bundled static data.';
dataSourceLabel = jsonPath;
lastSavedSnapshot = JSON.stringify(networkData);
saveState = 'saved';
+10
View File
@@ -1,5 +1,6 @@
import {
checkWritableState as checkWritableStateCore,
getWritableState as getWritableStateCore,
isWriteEnabled as isWriteEnabledCore,
readNetworkFile as readNetworkFileCore,
writeNetworkFile as writeNetworkFileCore
@@ -12,6 +13,11 @@ export interface NetworkFileMetadata {
updatedAt: string;
}
export interface WritableState {
writable: boolean;
reason: string | null;
}
export function isWriteEnabled(): boolean {
return isWriteEnabledCore();
}
@@ -24,6 +30,10 @@ export async function writeNetworkFile(data: NetworkData): Promise<NetworkFileMe
return (await writeNetworkFileCore(data)) as NetworkFileMetadata;
}
export async function getWritableState(): Promise<WritableState> {
return (await getWritableStateCore()) as WritableState;
}
export async function checkWritableState(): Promise<boolean> {
return checkWritableStateCore();
}
+84 -9
View File
@@ -16,6 +16,7 @@ import path from 'node:path';
* @typedef {{ machines: unknown[]; devices: unknown[] }} NetworkData
* @typedef {{ source: string; updatedAt: string }} NetworkFileMetadata
* @typedef {{ data: NetworkData } & NetworkFileMetadata} NetworkFileReadResult
* @typedef {{ writable: boolean; reason: string | null }} WritableState
*/
const NETWORK_READ_ONLY = process.env.NETWORK_READ_ONLY === 'true';
@@ -43,6 +44,38 @@ export function isWriteEnabled() {
return !NETWORK_READ_ONLY;
}
/**
* @param {unknown} error
* @returns {string}
*/
function formatFileSystemErrorCode(error) {
if (error && typeof error === 'object' && 'code' in error && typeof error.code === 'string') {
return error.code;
}
return 'UNKNOWN';
}
/**
* @param {string} directory
* @param {string} label
* @returns {Promise<string | null>}
*/
async function assertDirectoryWritable(directory, label) {
try {
await mkdir(directory, { recursive: true });
} catch (error) {
return `${label} directory "${directory}" could not be created (${formatFileSystemErrorCode(error)}).`;
}
try {
await access(directory, constants.W_OK);
} catch (error) {
return `${label} directory "${directory}" is not writable (${formatFileSystemErrorCode(error)}).`;
}
return null;
}
/**
* @param {string} dataFilePath
* @returns {Promise<string>}
@@ -151,20 +184,62 @@ export async function writeNetworkFile(data) {
}
/**
* @returns {Promise<boolean>}
* @returns {Promise<WritableState>}
*/
export async function checkWritableState() {
export async function getWritableState() {
if (!isWriteEnabled()) {
return false;
return {
writable: false,
reason: 'Writes disabled by NETWORK_READ_ONLY=true.'
};
}
const source = resolveDataFilePath();
const directory = path.dirname(source);
try {
await mkdir(directory, { recursive: true });
await access(directory, constants.W_OK);
} catch {
return false;
const dataDirectoryError = await assertDirectoryWritable(directory, 'Data');
if (dataDirectoryError) {
return {
writable: false,
reason: dataDirectoryError
};
}
return true;
const backupDirectory = resolveBackupDirectory();
const backupDirectoryError = await assertDirectoryWritable(backupDirectory, 'Backup');
if (backupDirectoryError) {
return {
writable: false,
reason: backupDirectoryError
};
}
try {
await access(source, constants.F_OK);
} catch {
return {
writable: true,
reason: null
};
}
try {
await access(source, constants.R_OK | constants.W_OK);
} catch (error) {
return {
writable: false,
reason: `Data file "${source}" exists but is not readable and writable (${formatFileSystemErrorCode(error)}).`
};
}
return {
writable: true,
reason: null
};
}
/**
* @returns {Promise<boolean>}
*/
export async function checkWritableState() {
return (await getWritableState()).writable;
}
+20 -9
View File
@@ -2,8 +2,7 @@ import { json } from '@sveltejs/kit';
import { validateNetworkData } from '$lib/data/networkSchema';
import {
checkWritableState,
isWriteEnabled,
getWritableState,
readNetworkFile,
writeNetworkFile
} from '$lib/server/networkPersistence';
@@ -16,11 +15,18 @@ function serializeValidationErrors(errors: Array<{ path: string; message: string
}));
}
function resolveReadOnlyErrorMessage(reason: string | null): string {
if (!reason) {
return 'Write API unavailable in current deployment.';
}
return `Write API unavailable: ${reason}`;
}
export const GET: RequestHandler = async () => {
try {
const [{ data, source, updatedAt }, writable] = await Promise.all([
const [{ data, source, updatedAt }, writableState] = await Promise.all([
readNetworkFile(),
checkWritableState()
getWritableState()
]);
const validation = validateNetworkData(data);
if (!validation.valid || !validation.data) {
@@ -35,7 +41,8 @@ export const GET: RequestHandler = async () => {
return json({
data: validation.data,
writable,
writable: writableState.writable,
writableReason: writableState.reason,
source,
updatedAt
});
@@ -47,10 +54,13 @@ export const GET: RequestHandler = async () => {
};
export const PUT: RequestHandler = async ({ request }) => {
if (!isWriteEnabled()) {
const writableStateBeforeWrite = await getWritableState();
if (!writableStateBeforeWrite.writable) {
return json(
{
error: 'Write API disabled. Unset NETWORK_READ_ONLY to enable persistence.'
error: resolveReadOnlyErrorMessage(writableStateBeforeWrite.reason),
writable: false,
writableReason: writableStateBeforeWrite.reason
},
{ status: 403 }
);
@@ -76,10 +86,11 @@ export const PUT: RequestHandler = async ({ request }) => {
try {
const metadata = await writeNetworkFile(validation.data);
const writable = await checkWritableState();
const writableStateAfterWrite = await getWritableState();
return json({
data: validation.data,
writable,
writable: writableStateAfterWrite.writable,
writableReason: writableStateAfterWrite.reason,
source: metadata.source,
updatedAt: metadata.updatedAt
});
+198 -120
View File
@@ -5,6 +5,47 @@
"ipAddress": "10.0.0.3",
"role": "Hypervisor",
"operatingSystem": "Proxmox",
"iconKey": "homarr:proxmox",
"software": {
"vms": [
{
"name": "OpnSense",
"role": "Router/Firewall/Gateway (DHCP 10.0.0.100-254)",
"ipAddress": "10.0.0.1"
},
{
"name": "TPLink Omada Controller",
"role": "Network Controller (:8043)",
"ipAddress": "10.0.0.4"
},
{
"name": "PiVPN (WireGuard)",
"role": "VPN Server",
"ipAddress": "10.0.0.5"
},
{
"name": "PiHole",
"role": "DNS Ad-blocker (installed, not in active use)",
"ipAddress": "10.0.0.6"
},
{
"name": "Dashy",
"role": "Dashboard",
"ipAddress": "10.0.0.12"
},
{
"name": "ProxRouter-Docker",
"role": "Docker host (Nginx reverse proxy, RustDesk, TwinGate)",
"ipAddress": "10.0.0.23"
}
]
},
"hardware": {
"cpu": "Intel N100",
"ram": "8GB",
"networkPorts": 4,
"networkPortSpeedGbps": 1
},
"ports": [
{
"portName": "eth0",
@@ -34,45 +75,23 @@
"port": "wan"
}
}
],
"software": {
"vms": [
{
"name": "OpnSense",
"role": "Router/Firewall/Gateway (DHCP 10.0.0.100-254)",
"ipAddress": "10.0.0.1"
},
{
"name": "TPLink Omada Controller",
"role": "Network Controller (:8043)",
"ipAddress": "10.0.0.4"
},
{ "name": "PiVPN (WireGuard)", "role": "VPN Server", "ipAddress": "10.0.0.5" },
{
"name": "PiHole",
"role": "DNS Ad-blocker (installed, not in active use)",
"ipAddress": "10.0.0.6"
},
{ "name": "Dashy", "role": "Dashboard", "ipAddress": "10.0.0.12" },
{
"name": "ProxRouter-Docker",
"role": "Docker host (Nginx reverse proxy, RustDesk, TwinGate)",
"ipAddress": "10.0.0.23"
}
]
},
"hardware": {
"cpu": "Intel N100",
"ram": "8GB",
"networkPorts": 4,
"networkPortSpeedGbps": 1
}
]
},
{
"machineName": "Asustor NAS",
"ipAddress": "10.0.0.9",
"role": "NAS",
"operatingSystem": "Asustor ADM",
"iconKey": "homarr:asustor",
"software": {
"vms": []
},
"hardware": {
"cpu": "Realtek RTD1296 Quad Core 1.4GHz",
"ram": "2GB",
"networkPorts": 1,
"networkPortSpeedGbps": 1
},
"ports": [
{
"portName": "eth0",
@@ -82,20 +101,23 @@
"port": "3"
}
}
],
"software": { "vms": [] },
"hardware": {
"cpu": "Realtek RTD1296 Quad Core 1.4GHz",
"ram": "2GB",
"networkPorts": 1,
"networkPortSpeedGbps": 1
}
]
},
{
"machineName": "Home Assistant Green",
"ipAddress": "10.0.0.13",
"role": "Smart Home Controller",
"operatingSystem": "Home Assistant OS",
"iconKey": "homarr:home-assistant",
"software": {
"vms": []
},
"hardware": {
"cpu": "Home Assistant Custom SoC",
"ram": "Unknown",
"networkPorts": 1,
"networkPortSpeedGbps": 1
},
"ports": [
{
"portName": "eth0",
@@ -105,20 +127,23 @@
"port": "4"
}
}
],
"software": { "vms": [] },
"hardware": {
"cpu": "Home Assistant Custom SoC",
"ram": "Unknown",
"networkPorts": 1,
"networkPortSpeedGbps": 1
}
]
},
{
"machineName": "Plex Server",
"ipAddress": "10.0.0.11",
"role": "Media Server",
"operatingSystem": "Ubuntu Server",
"iconKey": "homarr:plex",
"software": {
"vms": []
},
"hardware": {
"cpu": "Intel N100",
"ram": "Unknown",
"networkPorts": 1,
"networkPortSpeedGbps": 1
},
"ports": [
{
"portName": "eth0",
@@ -128,20 +153,23 @@
"port": "5"
}
}
],
"software": { "vms": [] },
"hardware": {
"cpu": "Intel N100",
"ram": "Unknown",
"networkPorts": 1,
"networkPortSpeedGbps": 1
}
]
},
{
"machineName": "Win11 N100",
"ipAddress": "10.0.0.8",
"role": "Media Downloader",
"operatingSystem": "Windows 11",
"iconKey": "homarr:windows-11",
"software": {
"vms": []
},
"hardware": {
"cpu": "Intel N100",
"ram": "Unknown",
"networkPorts": 1,
"networkPortSpeedGbps": 1
},
"ports": [
{
"portName": "eth0",
@@ -151,20 +179,40 @@
"port": "6"
}
}
],
"software": { "vms": [] },
"hardware": {
"cpu": "Intel N100",
"ram": "Unknown",
"networkPorts": 1,
"networkPortSpeedGbps": 1
}
]
},
{
"machineName": "Win11 Backblaze NAS",
"ipAddress": "10.0.0.7",
"role": "Backup NAS + Hypervisor",
"operatingSystem": "TrueNAS Scale",
"iconKey": "homarr:backblaze",
"software": {
"vms": [
{
"name": "Win11NAS",
"role": "Backblaze Backup VM",
"ipAddress": "10.0.0.24"
},
{
"name": "MakeMKV",
"role": "Blu-ray Ripper",
"ipAddress": "10.0.0.14"
},
{
"name": "Handbrake",
"role": "Video Transcoder",
"ipAddress": "10.0.0.15"
}
]
},
"hardware": {
"cpu": "AMD Ryzen 5 4600G",
"ram": "16GB",
"networkPorts": 1,
"networkPortSpeedGbps": 1,
"gpu": "EVGA GeForce GTX 1050 Ti"
},
"ports": [
{
"portName": "eth0",
@@ -174,37 +222,14 @@
"port": "7"
}
}
],
"software": {
"vms": [
{ "name": "Win11NAS", "role": "Backblaze Backup VM", "ipAddress": "10.0.0.24" },
{ "name": "MakeMKV", "role": "Blu-ray Ripper", "ipAddress": "10.0.0.14" },
{ "name": "Handbrake", "role": "Video Transcoder", "ipAddress": "10.0.0.15" }
]
},
"hardware": {
"cpu": "AMD Ryzen 5 4600G",
"ram": "16GB",
"networkPorts": 1,
"networkPortSpeedGbps": 1,
"gpu": "EVGA GeForce GTX 1050 Ti"
}
]
},
{
"machineName": "TrueNAS Host",
"ipAddress": "10.0.0.10",
"role": "Storage + VM Host",
"operatingSystem": "TrueNAS Scale",
"ports": [
{
"portName": "eth0",
"speedGbps": 1,
"connectedTo": {
"device": "Gigabit Switch",
"port": "8"
}
}
],
"iconKey": "homarr:truenas",
"software": {
"vms": [
{
@@ -219,13 +244,45 @@
"ram": "Unknown",
"networkPorts": 1,
"networkPortSpeedGbps": 1
}
},
"ports": [
{
"portName": "eth0",
"speedGbps": 1,
"connectedTo": {
"device": "Gigabit Switch",
"port": "8"
}
}
]
},
{
"machineName": "AI Server",
"ipAddress": "10.0.0.20",
"role": "AI Dev/Inference",
"operatingSystem": "Pop!_OS",
"iconKey": "homarr:ollama-dark",
"software": {
"vms": [
{
"name": "Ollama",
"role": "LLM Inference",
"ipAddress": "10.0.0.21"
},
{
"name": "Bot Training",
"role": "AI Training",
"ipAddress": "10.0.0.22"
}
]
},
"hardware": {
"cpu": "AMD Ryzen 5 3600",
"ram": "32GB",
"networkPorts": 1,
"networkPortSpeedGbps": 1,
"gpu": "Gigabyte GeForce GTX 1080"
},
"ports": [
{
"portName": "eth0",
@@ -235,26 +292,23 @@
"port": "9"
}
}
],
"software": {
"vms": [
{ "name": "Ollama", "role": "LLM Inference", "ipAddress": "10.0.0.21" },
{ "name": "Bot Training", "role": "AI Training", "ipAddress": "10.0.0.22" }
]
},
"hardware": {
"cpu": "AMD Ryzen 5 3600",
"ram": "32GB",
"networkPorts": 1,
"networkPortSpeedGbps": 1,
"gpu": "Gigabyte GeForce GTX 1080"
}
]
},
{
"machineName": "Immich Mini PC",
"ipAddress": "10.0.0.30",
"role": "Photo Server",
"operatingSystem": "Linux",
"iconKey": "homarr:immich",
"software": {
"vms": []
},
"hardware": {
"cpu": "Unknown",
"ram": "Unknown",
"networkPorts": 1,
"networkPortSpeedGbps": 1
},
"ports": [
{
"portName": "eth0",
@@ -264,14 +318,7 @@
"port": "10"
}
}
],
"software": { "vms": [] },
"hardware": {
"cpu": "Unknown",
"ram": "Unknown",
"networkPorts": 1,
"networkPortSpeedGbps": 1
}
]
}
],
"devices": [
@@ -279,6 +326,7 @@
"name": "Gigabit Switch",
"ipAddress": "unknown",
"type": "Network Switch",
"iconKey": "switch",
"notes": "Main 24-port switch. Wireless access point uplinks through this switch.",
"ports": [
{
@@ -403,7 +451,11 @@
},
{
"portName": "20",
"speedGbps": 1
"speedGbps": 1,
"connectedTo": {
"device": "NanoKVM Lite",
"port": "port0"
}
},
{
"portName": "21",
@@ -443,6 +495,7 @@
"name": "HDHomeRun",
"ipAddress": "10.0.0.2",
"type": "TV Tuner",
"iconKey": "homarr:hdhomerun",
"ports": [
{
"portName": "eth0",
@@ -458,37 +511,62 @@
"name": "3DS",
"ipAddress": "10.0.0.17",
"type": "Handheld Console",
"notes": "Wi-Fi only."
"notes": "Wi-Fi only.",
"ports": []
},
{
"name": "2DS",
"ipAddress": "10.0.0.18",
"type": "Handheld Console",
"notes": "Wi-Fi only."
"notes": "Wi-Fi only.",
"ports": []
},
{
"name": "Nintendo Switch",
"ipAddress": "10.0.0.19",
"type": "Gaming Console",
"notes": "Wi-Fi only."
"notes": "Wi-Fi only.",
"ports": [
{
"portName": "port0",
"speedGbps": 1
}
]
},
{
"name": "NanoKVM Lite",
"ipAddress": "10.0.0.26",
"type": "KVM Device",
"notes": "Port link not yet modeled."
"notes": "Port link not yet modeled.",
"ports": [
{
"portName": "port0",
"speedGbps": 1,
"connectedTo": {
"device": "Gigabit Switch",
"port": "20"
}
}
]
},
{
"name": "UPS Pi",
"ipAddress": "10.0.0.27",
"type": "Power Monitoring Device",
"notes": "Port link not yet modeled."
"notes": "Port link not yet modeled.",
"ports": [
{
"portName": "port0",
"speedGbps": 1
}
]
},
{
"name": "Waveshare",
"ipAddress": "10.0.0.28",
"type": "Peripheral Device",
"notes": "Port link not yet modeled."
"notes": "Port link not yet modeled.",
"ports": []
}
]
}