Skip to content

Commit 24d0fe5

Browse files
bradleygauthierbradleygauthier
committed
feat: Makefile, admin dashboard section in README, project structure update
Makefile with 25 targets: setup, service management (register/deregister/ status), monitoring (hardware, containers), certificates (list/rotate/ inspect/trust), DNS (list/flush/resolve), audit verification, admin UI (dev/build/install/typecheck), and testing (unit/integration/smoke/ui). README updates: Admin UI badge, dashboard section with ASCII wireframe, project structure includes ui/ directory, docs index cleaned up.
1 parent 592c21f commit 24d0fe5

2 files changed

Lines changed: 196 additions & 7 deletions

File tree

‎Makefile‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# QP Conduit - Makefile
2+
# Internal infrastructure for on-premises AI deployments.
3+
# https://github.com/quantumpipes/conduit
4+
#
5+
# Override CONDUIT_APP_NAME to rebrand for your project.
6+
# Include this Makefile in your own: include path/to/conduit/Makefile
7+
8+
SHELL := /bin/bash
9+
.DEFAULT_GOAL := help
10+
11+
CONDUIT_DIR := $(shell dirname $(realpath $(lastword $(MAKEFILE_LIST))))
12+
UI_DIR := $(CONDUIT_DIR)/ui
13+
14+
# ---------------------------------------------------------------------------
15+
# Help
16+
# ---------------------------------------------------------------------------
17+
.PHONY: help
18+
help: ## Show this help
19+
@echo ""
20+
@echo " QP Conduit - On-Premises Infrastructure"
21+
@echo " ========================================"
22+
@echo ""
23+
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
24+
awk 'BEGIN {FS = ":.*?## "}; {printf " \033[36m%-26s\033[0m %s\n", $$1, $$2}'
25+
@echo ""
26+
27+
# ---------------------------------------------------------------------------
28+
# Setup
29+
# ---------------------------------------------------------------------------
30+
.PHONY: conduit-setup
31+
conduit-setup: ## Initialize Conduit (dnsmasq, Caddy, internal CA)
32+
@bash $(CONDUIT_DIR)/conduit-setup.sh
33+
34+
# ---------------------------------------------------------------------------
35+
# Service Management
36+
# ---------------------------------------------------------------------------
37+
.PHONY: conduit-register
38+
conduit-register: ## Register a service (NAME=grafana HOST=10.0.1.50:3000)
39+
@bash $(CONDUIT_DIR)/conduit-register.sh --name $(NAME) --host $(HOST) \
40+
$(if $(HEALTH),--health $(HEALTH),) \
41+
$(if $(NO_TLS),--no-tls,)
42+
43+
.PHONY: conduit-deregister
44+
conduit-deregister: ## Remove a service (NAME=grafana)
45+
@bash $(CONDUIT_DIR)/conduit-deregister.sh --name $(NAME)
46+
47+
.PHONY: conduit-status
48+
conduit-status: ## Show all services with health, TLS, and DNS status
49+
@bash $(CONDUIT_DIR)/conduit-status.sh
50+
51+
# ---------------------------------------------------------------------------
52+
# Monitoring
53+
# ---------------------------------------------------------------------------
54+
.PHONY: conduit-monitor
55+
conduit-monitor: ## Show hardware stats (GPU, CPU, memory, disk)
56+
@bash $(CONDUIT_DIR)/conduit-monitor.sh $(if $(SERVER),--server $(SERVER),)
57+
58+
.PHONY: conduit-monitor-containers
59+
conduit-monitor-containers: ## Show Docker container health
60+
@bash $(CONDUIT_DIR)/conduit-monitor.sh --containers
61+
62+
# ---------------------------------------------------------------------------
63+
# Certificates
64+
# ---------------------------------------------------------------------------
65+
.PHONY: conduit-certs
66+
conduit-certs: ## List all TLS certificates with expiry dates
67+
@bash $(CONDUIT_DIR)/conduit-certs.sh
68+
69+
.PHONY: conduit-certs-rotate
70+
conduit-certs-rotate: ## Rotate a certificate (NAME=grafana)
71+
@bash $(CONDUIT_DIR)/conduit-certs.sh --rotate $(NAME)
72+
73+
.PHONY: conduit-certs-inspect
74+
conduit-certs-inspect: ## Inspect a certificate (NAME=grafana)
75+
@bash $(CONDUIT_DIR)/conduit-certs.sh --inspect $(NAME)
76+
77+
.PHONY: conduit-certs-trust
78+
conduit-certs-trust: ## Install internal CA in system trust store
79+
@bash $(CONDUIT_DIR)/conduit-certs.sh --trust
80+
81+
# ---------------------------------------------------------------------------
82+
# DNS
83+
# ---------------------------------------------------------------------------
84+
.PHONY: conduit-dns
85+
conduit-dns: ## List all DNS entries
86+
@bash $(CONDUIT_DIR)/conduit-dns.sh
87+
88+
.PHONY: conduit-dns-flush
89+
conduit-dns-flush: ## Flush DNS cache
90+
@bash $(CONDUIT_DIR)/conduit-dns.sh --flush
91+
92+
.PHONY: conduit-dns-resolve
93+
conduit-dns-resolve: ## Test DNS resolution (DOMAIN=grafana.internal)
94+
@bash $(CONDUIT_DIR)/conduit-dns.sh --resolve $(DOMAIN)
95+
96+
# ---------------------------------------------------------------------------
97+
# Audit
98+
# ---------------------------------------------------------------------------
99+
.PHONY: conduit-verify
100+
conduit-verify: ## Verify Capsule audit chain integrity
101+
@bash -c 'source $(CONDUIT_DIR)/conduit-preflight.sh && qp-capsule verify'
102+
103+
# ---------------------------------------------------------------------------
104+
# Admin UI
105+
# ---------------------------------------------------------------------------
106+
.PHONY: ui
107+
ui: ## Start the admin dashboard (dev mode, port 5173)
108+
@cd $(UI_DIR) && npm run dev
109+
110+
.PHONY: ui-build
111+
ui-build: ## Build the admin dashboard for production
112+
@cd $(UI_DIR) && npm run build
113+
114+
.PHONY: ui-install
115+
ui-install: ## Install admin dashboard dependencies
116+
@cd $(UI_DIR) && npm install
117+
118+
.PHONY: ui-typecheck
119+
ui-typecheck: ## Type-check the admin dashboard
120+
@cd $(UI_DIR) && npm run typecheck
121+
122+
# ---------------------------------------------------------------------------
123+
# Testing
124+
# ---------------------------------------------------------------------------
125+
.PHONY: test
126+
test: ## Run all tests (requires bats-core)
127+
@bats $(CONDUIT_DIR)/tests/unit/ $(CONDUIT_DIR)/tests/integration/
128+
129+
.PHONY: test-unit
130+
test-unit: ## Run unit tests only
131+
@bats $(CONDUIT_DIR)/tests/unit/
132+
133+
.PHONY: test-integration
134+
test-integration: ## Run integration tests only
135+
@bats $(CONDUIT_DIR)/tests/integration/
136+
137+
.PHONY: test-smoke
138+
test-smoke: ## Run smoke tests
139+
@bash $(CONDUIT_DIR)/tests/smoke/test_standalone.sh
140+
141+
.PHONY: test-ui
142+
test-ui: ## Run admin dashboard tests
143+
@cd $(UI_DIR) && npm test
144+
145+
.PHONY: check
146+
check: test ui-typecheck ## Run all tests + type-check UI

‎README.md‎

Lines changed: 50 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ Tunnel gets you in. Conduit connects everything inside. Automatic DNS, internal
99
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
1010
[![Crypto](https://img.shields.io/badge/Crypto-Internal_CA_%2B_TLS_1.3-purple.svg)](#security)
1111
[![Capsule](https://img.shields.io/badge/Audit-Capsule_Protocol-orange.svg)](https://github.com/quantumpipes/capsule)
12+
[![Admin UI](https://img.shields.io/badge/UI-React_19_%2B_OKLCH-ff69b4.svg)](#admin-dashboard)
1213

1314
</div>
1415

@@ -277,6 +278,43 @@ The JSON audit log is the fast local index. Capsules are the cryptographic sourc
277278

278279
---
279280

281+
## Admin Dashboard
282+
283+
Conduit includes a browser-based admin UI for managing your entire on-premises infrastructure visually.
284+
285+
```bash
286+
make ui-install # First time: install dependencies
287+
make ui # Start the dashboard (http://localhost:5173)
288+
```
289+
290+
```
291+
┌──────────────────────────────────────────────────────────────────────┐
292+
│ QP Conduit │
293+
├──────────┬───────────────────────────────────────────────────────────┤
294+
│ │ Services 4 up · 0 degraded · 0 down │
295+
│ Overview │ │
296+
│ ┌──────┐ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
297+
│ │Dashbd│ │ │ Hub │ │ Core API │ │ Grafana │ │
298+
│ ├──────┤ │ │ ● hub.local │ │ ● api.local │ │ ● grafana │ │
299+
│ │Svc │ │ │ :4200 TLS ✓ │ │ :8000 TLS ✓ │ │ .internal │ │
300+
│ │DNS │ │ │ 12ms healthy │ │ 8ms healthy │ │ 15ms healthy │ │
301+
│ │TLS │ │ └──────────────┘ └──────────────┘ └──────────────┘ │
302+
│ ├──────┤ │ │
303+
│ │Server│ │ GPU Server (10.0.1.20) │
304+
│ │Route │ │ GPU 0: H200 87% ███████░░ 72/141 GB 62°C │
305+
│ └──────┘ │ GPU 1: H200 43% ████░░░░░ 31/141 GB 58°C │
306+
│ │ CPU: 24/48 Mem: 189/256 GB Disk: 1.2/3.8 TB │
307+
└──────────┴───────────────────────────────────────────────────────────┘
308+
```
309+
310+
**Six views**: Dashboard (health overview), Services (register/manage), DNS (entries + resolver), TLS (certificates + CA), Servers (GPU/CPU/memory), Routing (proxy routes).
311+
312+
**Tech**: React 19, TypeScript, Vite, TailwindCSS 4 with OKLCH perceptual color system, Zustand, TanStack Query. Dark theme with 6-level surface hierarchy.
313+
314+
**Keyboard-first**: `1-6` switches views, `/` focuses search, `Esc` dismisses panels.
315+
316+
---
317+
280318
## Security
281319

282320
| Layer | Mechanism |
@@ -357,10 +395,8 @@ All values are overridable via environment variables or `.env.conduit`.
357395
|----------|----------|
358396
| [Architecture](./docs/architecture.md) | Developers, Auditors |
359397
| [Security Evaluation](./docs/security.md) | CISOs, Security Teams |
398+
| [Why Conduit](./docs/why-conduit.md) | Decision-Makers, Architects |
360399
| [Compliance Mappings](./docs/compliance/) | Regulators, GRC |
361-
| [Internal TLS](./docs/internal-tls.md) | Network Engineers |
362-
| [Monitoring](./docs/monitoring.md) | DevOps, SREs |
363-
| [Narrative Guide](./docs/GUIDE.md) | New Users |
364400

365401
### Examples
366402

@@ -384,13 +420,20 @@ All values are overridable via environment variables or `.env.conduit`.
384420
│ ├── audit.sh # Structured audit logging + Capsule sealing
385421
│ ├── dns.sh # dnsmasq configuration and management
386422
│ ├── tls.sh # Caddy CA and certificate operations
387-
│ ├── routing.sh # Reverse proxy route management
388-
│ └── monitor.sh # Hardware and container monitoring
423+
│ └── routing.sh # Reverse proxy route management
424+
├── ui/ # Admin dashboard (React 19 + TypeScript)
425+
│ └── src/
426+
│ ├── components/views/ # 6 views (dashboard, services, dns, tls, servers, routing)
427+
│ ├── components/layout/ # AppShell, Sidebar, StatusBar
428+
│ ├── components/shared/ # HealthDot, StatCard, Chip, SlideOver, Toast
429+
│ ├── api/ # Typed API client modules
430+
│ ├── stores/ # Zustand state management
431+
│ └── lib/ # Types, utilities, OKLCH theme
389432
├── templates/
390-
│ └── Caddyfile.conduit.tpl # Caddy configuration template
433+
│ └── Caddyfile.service.tpl # Per-service Caddy configuration template
391434
├── conformance/ # Audit log golden test vectors
392435
├── completions/ # Bash and Zsh tab-completion scripts
393-
├── tests/ # Unit, integration, and smoke tests
436+
├── tests/ # Unit, integration, and smoke tests (bats-core)
394437
├── docs/ # Architecture, security, compliance, guides
395438
├── examples/ # Deployment walkthroughs
396439
├── .env.conduit.example # Configuration template

0 commit comments

Comments
 (0)