If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/0xJacky/nginx-ui shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit today
• 8 active contributors
• AGPL-3.0 licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 70% of recent commits
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live 0xJacky/nginx-ui repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/0xJacky/nginx-ui.

What it runs against: a local clone of 0xJacky/nginx-ui — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in 0xJacky/nginx-ui | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch dev exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of 0xJacky/nginx-ui. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/0xJacky/nginx-ui.git
#   cd nginx-ui
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of 0xJacky/nginx-ui and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "0xJacky/nginx-ui(\\.git)?\\b" \\
  && ok "origin remote is 0xJacky/nginx-ui" \\
  || miss "origin remote is not 0xJacky/nginx-ui (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify dev >/dev/null 2>&1 \\
  && ok "default branch dev exists" \\
  || miss "default branch dev no longer exists"

# 4. Critical files exist
test -f "api/api.go" \\
  && ok "api/api.go" \\
  || miss "missing critical file: api/api.go"
test -f "api/config/router.go" \\
  && ok "api/config/router.go" \\
  || miss "missing critical file: api/config/router.go"
test -f "api/cluster/router.go" \\
  && ok "api/cluster/router.go" \\
  || miss "missing critical file: api/cluster/router.go"
test -f ".devcontainer/docker-compose.yml" \\
  && ok ".devcontainer/docker-compose.yml" \\
  || miss "missing critical file: .devcontainer/docker-compose.yml"
test -f "api/certificate/router.go" \\
  && ok "api/certificate/router.go" \\
  || miss "missing critical file: api/certificate/router.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/0xJacky/nginx-ui"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

nginx-ui is a Go + Vue 3 web dashboard for managing Nginx configurations and monitoring without touching config files directly. It provides a GUI to create/edit server blocks, upstream groups, SSL certificates, and view real-time Nginx metrics—solving the pain of manual nginx.conf editing and syntax validation. Go backend (main application logic, likely under a cmd/ or internal/ directory not listed) paired with Vue 3 SPA frontend in src/. Frontend uses Ant Design Vue component library, Pinia for state (with persistence plugin), and Vue Router for navigation. Monolithic structure: single Go binary embeds frontend assets (evident from .github/embed.go), deployed as a single container.

DevOps engineers and sysadmins who manage Nginx servers and want a visual alternative to SSH + manual config editing; teams deploying web services who need quick Nginx reconfiguration without terminal access.

Actively maintained and production-ready. The project has significant GitHub stars, structured CI/CD via GitHub Actions (.github/workflows/build.yml, codeql.yml), organized issue templates, and a well-documented devcontainer setup. Recent releases and organized codebase structure indicate sustained development, though it's not a mega-corporation project.

Moderate risk: 2.5M LOC in Go suggests complexity; 900K+ LOC in Vue indicates a substantial frontend. Dependency count is high (~40+ npm packages visible in package.json), increasing supply-chain exposure. Single-maintainer perception (0xJacky) creates continuity risk, though Hintay and Akino are listed as co-developers. No visible test directory in the file list is a red flag for stability confidence.

Active release cycle (renovate.json indicates automated dependency updates), Weblate integration for i18n (weblate-pull.yml, weblate-sync.yml), and CodeQL security scanning enabled. Documentation building is automated (.github/workflows/documents.yml). The presence of devcontainer setup and CLAUDE.md/CLAUDE.mdc rules files suggests recent onboarding/contributor guidance work.

git clone https://github.com/0xJacky/nginx-ui.git
cd nginx-ui
pnpm install
pnpm run dev

Run from the project root; the frontend dev server starts on http://localhost:5173 (vite default). For full local dev with Nginx integration, use the .devcontainer/ setup: docker-compose up in .devcontainer/ directory.

Daily commands: Frontend only (requires running backend separately): pnpm run dev → http://localhost:5173. Full stack locally (with Nginx): Use .devcontainer/docker-compose.yml: cd .devcontainer && docker-compose up, then visit http://localhost:9000 (typical nginx-ui port). Production build: pnpm run build creates optimized dist/ folder embedded into Go binary.

• api/api.go — Main API entry point and router setup; every contributor must understand the API structure and middleware composition
• api/config/router.go — Core Nginx config management routes; most features depend on reading/writing configuration files
• api/cluster/router.go — Multi-node Nginx cluster management; critical for understanding distributed Nginx UI deployments
• .devcontainer/docker-compose.yml — Development environment setup with Nginx, Pebble ACME, and dependencies; essential for local development workflow
• api/certificate/router.go — ACME certificate issuance and renewal orchestration; handles SSL/TLS lifecycle
• api/backup/router.go — Configuration backup and restore operations; critical for data safety and disaster recovery
• api/audit/middleware.go — Request logging and audit trail middleware; tracks all configuration changes for security compliance

Add a new API endpoint for Nginx config operations

1. Create new handler file in api/config/ (e.g., api/config/validate.go) with your business logic (api/config/validate.go)
2. Register GET/POST routes in api/config/router.go using chi.Router methods (api/config/router.go)
3. Add request/response structs if needed in api/config/ and ensure audit middleware logs the operation (api/audit/middleware.go)
4. Test the endpoint with curl or in devcontainer by running the backend via .air.toml hot-reload (.air.toml)

Add a new ACME certificate provider (DNS challenge type)

1. Create dns provider implementation in api/certificate/dns_provider.go or new file with DNS API calls (api/certificate/dns_provider.go)
2. Register new provider with resolver in api/certificate/issue.go and update DNS credential handling (api/certificate/issue.go)
3. Store provider credentials encrypted via api/crypto/crypto.go using AES encryption (api/crypto/crypto.go)
4. Expose provider selection in api/certificate/router.go GET/POST handlers for frontend selection (api/certificate/router.go)

Add a new real-time metric or analytics feed

1. Implement metric collection logic in api/analytic/analytic.go or new file that queries Nginx stats (api/analytic/analytic.go)
2. Create WebSocket handler in api/analytic/ws_keepalive.go to stream metrics with keepalive pings (api/analytic/ws_keepalive.go)
3. Register WebSocket route in api/analytic/router.go with chi.Get() handler wrapping gorilla/websocket (api/analytic/router.go)
4. Define metric DTO in api/analytic/type.go with JSON struct tags for type-safe serialization (api/analytic/type.go)

Add a new multi-node cluster feature

1. Define cluster node/namespace models in api/cluster/node.go or api/cluster/namespace.go (api/cluster/namespace.go)
2. Implement cluster communication logic in api/cluster/websocket.go for inter-node sync (api/cluster/websocket.go)
3. Register cluster API routes in api/cluster/router.go (GET nodes, POST sync, DELETE node) (api/cluster/router.go)
4. Integrate with existing config, certificate, and analytic handlers to broadcast changes across cluster (api/config/router.go)

• Go + Chi router — Lightweight, fast HTTP server for Nginx management; Chi provides clean middleware composition and zero-allocation routing
• Vue 3 + TypeScript + Ant Design — Modern reactive frontend with strong typing; Ant Design provides enterprise UI components for config editing and cluster management
• WebSocket (Gorilla/websocket) + event streaming — Real-time metrics, logs, and cluster sync without polling overhead; keepalive ensures long-lived connections stay alive
• ACME (Let's Encrypt protocol) — Standard for automated SSL/TLS certificate issuance; supports DNS challenge for wildcard and non-public domains
• File-based config + version control — Nginx configs are text files on disk; backup/restore and history tracking via file snapshots; integrates with git for audit

• File-based config storage instead of database

  • Why: Nginx operates on flat text config files; keeping source-of-truth as files preserves Nginx's native workflow
  • Consequence: No transactional multi-config updates; file I/O latency; requires careful locking and backup strategies

• Multi-node cluster as eventual-consistent federation instead of centralized control plane

  • Why: Allows decentralized Nginx deployments across regions without single point of failure
  • Consequence: Complex sync logic, potential race conditions on config updates, eventual consistency delays (~1–5s)

• Synchronous ACME issuance (no job queue) instead of background workers

  • Why: Simplifies initial deployment; certificate requests are relatively rare operations
  • Consequence: Blocks HTTP request during DNS challenge wait (~30–60s); not suitable for high-volume certificate renewals

• In-memory WebSocket connections instead of Redis pub/sub

  • Why: Simpler setup for single-instance deployments; direct goroutine-based event broadcast
  • Consequence: Metrics and cluster events lost if backend restarts; scales poorly to multi-instance load-balanced setups

• Multi-user authentication with RBAC (no user model beyond WebAuthn session)
• Real-time log streaming (logs are read post-hoc, not streamed live)
• Windows Nginx support (development targets Linux/Docker)
• Database-backed persistence (all state is file-based or in-memory)
• Horizontal scaling with shared state (no Redis/etcd integration)

Dev environment assumes .devcontainer setup: Nginx management features require a running Nginx instance; bare pnpm run dev only tests frontend UI against mock APIs. Pebble ACME test certificates: SSL cert features in dev rely on Pebble mock CA (certs in .devcontainer/pebble-test/); production uses real ACME. Go binary embeds frontend: Frontend code must be built and embedded into the Go binary; changes to src/ require rebuilding the entire Go binary for testing. Weblate sync workflows: i18n strings are synced with external Weblate; manual translations may conflict with automated pulls. No visible test directory: Frontend tests likely missing or in a non-standard location; check for tests or .spec.ts files before modifying core logic.

• Embedded Assets (Go binary embedding) — nginx-ui's Go binary includes the entire Vue frontend; understanding how embed.go works is essential for modifying frontend without rebuilding the backend.
• Server-Sent Events (SSE) — The sse.js dependency powers real-time Nginx metric streaming from backend to frontend UI; critical for the monitoring dashboard feature.
• WebAuthn (FIDO2) — nginx-ui supports passwordless auth via @simplewebauthn/browser; knowing this pattern is important for securing access to production Nginx configs.
• ACME Protocol (Let's Encrypt) — The .devcontainer includes Pebble ACME server for cert testing; understanding ACME is essential for the SSL certificate automation features.
• Vue 3 Composition API + Pinia Store Persistence — The frontend heavily relies on Pinia with the persistedstate plugin for state management; this pattern is non-obvious and core to frontend architecture.
• Nginx Configuration as Code — nginx-ui converts manual .conf editing into programmatic config generation; understanding Nginx directives and block structure is prerequisite for contributing config management features.
• Hot Module Replacement (HMR) with Vite — The dev experience relies on Vite's HMR; understanding this is crucial for efficient frontend iteration during development.

• openresty/lua-nginx-module — Extends Nginx with Lua scripting; complementary to nginx-ui for dynamic request handling beyond static config.
• containous/traefik — Alternative reverse proxy with built-in UI and auto-config from Docker labels; direct competitor to nginx-ui in the modern DevOps stack.
• caddyserver/caddy — Modern reverse proxy with automatic HTTPS and Web UI; targets same use case (easier Nginx/proxy management) with different architecture.
• nginxinc/nginx-controller — Official NGINX Controller offering; commercial version solving the same config management problem at enterprise scale.
• kubernetes/ingress-nginx — Kubernetes Nginx Ingress Controller; if nginx-ui users migrate to K8s, this becomes the preferred way to manage Nginx.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add end-to-end tests for nginx config management workflows using Playwright

The repo has comprehensive backend API tests (api/backup/backup_test.go) and dev infrastructure (.devcontainer with pebble ACME server), but lacks E2E tests for critical user workflows. With the frontend being Vue 3 + Vite and backend in Go, adding Playwright E2E tests would cover the full stack: creating/editing nginx configs, applying changes, and certificate management. This is critical for a WebUI that controls nginx configs.

• [ ] Create .github/workflows/e2e-tests.yml GitHub Action workflow
• [ ] Add Playwright config file (playwright.config.ts) to frontend root
• [ ] Write E2E tests in tests/e2e/ for: nginx config CRUD operations, certificate renewal flow, and backup/restore workflows
• [ ] Integrate with existing .devcontainer setup to run against test nginx instance
• [ ] Reference .github/workflows/build.yml structure for consistency

Add frontend unit tests for critical utility functions and composables

The project uses @uozi-admin/curd and @vueuse/core extensively (visible in package.json and .cursor/rules/frontend.mdc), but there's no visible tests/ directory or jest/vitest configuration for frontend code. The analytics module (api/analytic/) and WebSocket handling (api/analytic/ws_keepalive.go) likely have Vue composables that need testing. Adding Vitest + Vue Test Utils would ensure frontend reliability.

• [ ] Create vitest.config.ts in frontend root with Vue plugin configuration
• [ ] Add tests/unit/ directory structure mirroring src/ layout
• [ ] Write tests for: API request interceptors (@uozi-admin/request usage), reactive state management (Pinia stores), and WebSocket/SSE connections (src/language/curd.ts likely has request utilities)
• [ ] Update package.json scripts with 'test' and 'test:coverage' entries
• [ ] Reference .vscode/tasks.json and .cursor/rules/frontend.mdc for context on frontend patterns

Add TypeScript strict mode enforcement and create type definitions for external API integrations

The repo uses typescript with vue-tsc for typechecking (package.json scripts), but tsconfig.json is missing from the file list, suggesting loose strictness settings. With multiple external integrations (@simplewebauthn/browser, @fingerprintjs/fingerprintjs, apexcharts), there's likely untyped API responses. Creating strict tsconfig settings and type definitions (especially for backend API responses) would prevent runtime errors in production.

• [ ] Create/review tsconfig.json to enable: strict: true, noImplicitAny: true, strictNullChecks: true
• [ ] Create src/types/api.ts with TypeScript interfaces for all backend API response shapes (reference api/api.go and api/audit/middleware.go)
• [ ] Create src/types/external.ts with type stubs for untyped dependencies (@fingerprintjs, jsencrypt, sse.js)
• [ ] Update lint:fix script in package.json to include 'typecheck' as prerequisite
• [ ] Add pre-commit hook or CI check (reference .github/workflows/codeql.yml) to enforce typecheck on PRs

• Add unit tests for Pinia stores: The repo lacks visible test files for state management. Create src/stores/__tests__/ directory and write tests for persistence plugin behavior using Vitest.: Medium
• Document the API contract: Extract and document Go API endpoints consumed by Vue components. Create docs/API.md listing routes, request/response schemas, and auth requirements based on existing backend code.: Low
• Add ESLint pre-commit hook: The lint script exists but isn't enforced pre-commit. Integrate husky + lint-staged to auto-fix code style on commits, reducing CI failures.: Low

• High · Outdated Dependencies with Known Vulnerabilities — package.json - dependencies section. Several dependencies have known security vulnerabilities. Notable concerns: axios 1.16.0 (has CVE-2024-28849 and CVE-2023-45133), highlight.js 11.11.1 (XSS vulnerabilities in certain versions), and marked 18.0.3 (potential XSS issues). The package.json shows no explicit version pinning or lock file mentioned, creating supply chain risk. Fix: Run 'npm audit' or 'pnpm audit', update vulnerable packages to patched versions. Implement automated dependency scanning in CI/CD pipeline. Pin exact versions in package-lock.json or pnpm-lock.yaml and commit it.
• High · Potential XSS Vulnerability via vue-dompurify-html — frontend dependencies - vue-dompurify-html, marked. The project uses vue-dompurify-html (5.3.0) and marked (18.0.3) for HTML rendering. If user input is processed through these libraries without proper sanitization before reaching them, XSS attacks are possible. The Nginx UI processes configuration files that may contain user-controlled content. Fix: Ensure all user-supplied content is sanitized before rendering. Use Content Security Policy (CSP) headers. Implement strict input validation on both frontend and backend. Review all usages of v-html and dompurify in Vue components.
• High · Potential Command Injection in Nginx Configuration Processing — api/config/ directory (add.go, delete.go, base_path.go). Based on the file structure (api/config/add.go, api/config/delete.go), the backend processes Nginx configuration files. If these APIs accept user input without proper validation and pass it to shell commands or Nginx reload operations, command injection is possible. Fix: Implement strict input validation and sanitization for all configuration inputs. Use parameterized/escaped operations when interacting with system commands. Never pass raw user input to os/exec. Implement allowlist validation for configuration syntax.
• High · Exposed Sensitive Ports in Docker Configuration — Dockerfile - EXPOSE directive. The Dockerfile exposes ports 80 and 443 without explicit security context. Combined with NGINX_UI_WORKING_DIR=/var/run/, there's risk of unauthorized access to the management interface if deployed without proper network segmentation. Fix: Implement network policies and firewall rules to restrict access to the UI ports. Use a reverse proxy with authentication. Consider running the container with read-only filesystem where possible. Implement role-based access control in the application.
• Medium · Weak Cryptography Library - jsencrypt — package.json - jsencrypt dependency. The project uses jsencrypt (3.5.4) for RSA encryption in the browser. This is an older, less-maintained library with potential cryptographic weaknesses. Browser-based encryption is also inherently weaker than server-side encryption. Fix: Consider using modern cryptography libraries like TweetNaCl.js or libsodium.js. Implement server-side encryption for sensitive data. Avoid storing sensitive data client-side when possible. Ensure proper key management practices.
• Medium · Missing Security Headers Configuration — resources/docker/nginx-ui.conf. The nginx configuration files (resources/docker/nginx.conf, resources/docker/nginx-ui.conf) are not visible in the provided structure. Without inspection, we cannot confirm presence of critical security headers (CSP, HSTS, X-Frame-Options, X-Content-Type-Options). Fix: Add security headers to Nginx configuration: add_header Strict-Transport-Security 'max-age=31536000; includeSubDomains' always; add_header X-Frame-Options 'SAMEORIGIN' always; add_header X-Content-Type-Options 'nosniff' always; add_header Content-Security-Policy 'default-src "self"' always;
• Medium · Potential Information Disclosure via Error Logs — Dockerfile - log creation commands. The Dockerfile creates access.log and error.log but doesn't show log rotation or access control configuration. Error logs from Nginx and the application could expose sensitive information about the system, configuration paths, or internal structure. Fix: Implement log rotation (

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.