Skip to content

IMPLEMENTATION.md

Latest commit

 

History

History
330 lines (250 loc) · 8.51 KB

IMPLEMENTATION.md

File metadata and controls

330 lines (250 loc) · 8.51 KB

NGINX Declarative API - Web UI Implementation Summary

Overview

A modern, full-featured React 19 TypeScript web interface has been created for the NGINX Declarative API v5.5. The UI provides a user-friendly way to manage NGINX configurations through the declarative API.

🎯 Features Implemented

Authentication

  • ✅ JWT-based authentication
  • ✅ Token stored in localStorage (with security disclaimer)
  • ✅ Protected routes
  • ✅ Automatic token injection in API requests
  • ✅ Auto-logout on 401 errors

UI Pages

  • ✅ Login Page - JWT token input with validation
  • ✅ Dashboard - Overview of configurations with status monitoring
  • ✅ Create Configuration - JSON editor for creating new configs
  • ✅ Configuration Management - View, edit, delete operations

API Integration

All v5.5 endpoints are integrated:

  • ✅ POST /v5.5/config - Create configuration
  • ✅ GET /v5.5/config/{configUid} - Retrieve configuration
  • ✅ PATCH /v5.5/config/{configUid} - Update configuration
  • ✅ DELETE /v5.5/config/{configUid} - Delete configuration
  • ✅ GET /v5.5/config/{configUid}/status - Get status
  • ✅ GET /v5.5/config/{configUid}/submission/{submissionUid} - Get async submission status

Testing

  • ✅ Test setup with Vitest
  • ✅ Component tests (LoginPage)
  • ✅ Store tests (AuthStore)
  • ✅ Hook tests (useConfig)
  • ✅ Coverage reporting configured

DevOps

  • ✅ Docker support with multi-stage build
  • ✅ NGINX reverse proxy configuration
  • ✅ Integration with docker-compose
  • ✅ Configurable ports
  • ✅ Development and production builds

📁 Project Structure

webui/
├── src/
│   ├── api/                  # API client layer
│   │   └── config.ts         # Config API methods
│   ├── components/           # Reusable components
│   │   ├── Header.tsx
│   │   ├── Layout.tsx
│   │   └── ProtectedRoute.tsx
│   ├── hooks/                # Custom React hooks
│   │   └── useConfig.ts      # React Query hooks for API
│   ├── lib/                  # Libraries & utilities
│   │   └── axios.ts          # Axios instance with interceptors
│   ├── pages/                # Page components
│   │   ├── LoginPage.tsx
│   │   ├── DashboardPage.tsx
│   │   └── CreateConfigPage.tsx
│   ├── store/                # State management
│   │   └── authStore.ts      # Zustand auth store
│   ├── test/                 # Test files
│   │   ├── setup.ts
│   │   ├── LoginPage.test.tsx
│   │   ├── authStore.test.ts
│   │   └── useConfig.test.tsx
│   ├── types/                # TypeScript definitions
│   │   └── index.ts          # API & app types
│   ├── App.tsx               # Main app with routing
│   ├── main.tsx              # Entry point
│   └── index.css             # Global styles
├── Dockerfile                # Production Docker build
├── nginx.conf                # NGINX config for production
├── vite.config.ts            # Vite configuration
├── tsconfig.json             # TypeScript config
├── package.json              # Dependencies
└── README.md                 # Web UI documentation

🛠 Technology Stack

Category Technology Purpose
Framework React 19 UI library
Language TypeScript Type safety
Build Tool Vite Fast dev server & build
Routing React Router v7 Client-side routing
State Management Zustand Auth state
Server State TanStack Query API state & caching
HTTP Client Axios API requests
UI Feedback React Hot Toast Notifications
Testing Vitest + Testing Library Unit & component tests
Code Quality ESLint + Prettier Linting & formatting

🚀 Getting Started

Development

cd webui
npm install
npm run dev

Access at http://localhost:3000

Running Tests

npm test              # Run tests
npm run test:ui       # Test UI
npm run test:coverage # Coverage report

Production Build

npm run build
npm run preview

Docker

# From repo root
cd contrib/docker-compose

# Build all images including Web UI
./nginx-dapi.sh -c build

# Start with default ports
./nginx-dapi.sh -c start

# Start with custom ports
./nginx-dapi.sh -c start -a 8080 -w 8081 -d 8082 -r 6380

Access Points:

🔐 Security Notes

Current Implementation (Development):

  • JWT tokens stored in localStorage
  • Simple Bearer token authentication
  • CORS handled by backend

⚠️ Production Recommendations:

  1. Use HTTP-only cookies for token storage
  2. Implement token refresh mechanism
  3. Add CSRF protection
  4. Enable rate limiting
  5. Use HTTPS/TLS in production
  6. Implement proper session management
  7. Add input validation and sanitization
  8. Consider OAuth2/OIDC for enterprise use

📋 Type Definitions

The UI includes comprehensive TypeScript types based on the OpenAPI spec:

interface ConfigDeclaration {
  output?: {
    type?: 'nms' | 'nginxone';
    license?: LicenseConfig;
    nms?: NMSConfig;
    nginxone?: NginxOneConfig;
  };
  declaration?: {
    http?: HttpConfig[];
    layer4?: Layer4Config[];
    resolvers?: ResolverConfig[];
  };
}

🎨 UI Design

Theme: Dark mode with gradient backgrounds

Color Scheme:

  • Primary: #646cff (purple-blue)
  • Success: #34c759 (green)
  • Error: #ff3b30 (red)
  • Background: Gradient from #1a1a2e to #16213e

Key Features:

  • Glassmorphism effects
  • Smooth animations and transitions
  • Responsive grid layouts
  • Status indicators with color coding
  • Monaco-style code editor aesthetics

📊 API Request Flow

User Action → React Component → React Query Hook → API Service → Axios → Backend API
                                        ↓
                              Cache & State Update
                                        ↓
                                  UI Re-render

🧪 Test Coverage

Tests implemented for:

  • ✅ Authentication store (login/logout)
  • ✅ Login page rendering
  • ✅ Config creation hook
  • ✅ API service layer (mocked)

Run npm run test:coverage for detailed coverage report.

🔄 State Management

Client State (Zustand):

  • Authentication state
  • User token
  • Login/logout actions

Server State (TanStack Query):

  • Configuration data
  • Status monitoring
  • Submission tracking
  • Automatic refetching
  • Optimistic updates

🌐 API Proxy Configuration

Development (Vite):

'/v5.5': {
  target: 'http://localhost:5000',
  changeOrigin: true,
}

Production (NGINX):

location /v5.5/ {
  proxy_pass http://nginx-dapi:5000;
  # ... proxy headers
}

📦 Docker Multi-Stage Build

  1. Build stage: Node.js 24 Alpine

    • Install dependencies
    • Build production bundle

  2. Production stage: NGINX Alpine

    • Copy built files
    • Serve with NGINX
    • Proxy API requests to backend

🎯 Future Enhancements

Planned Features

  • Form builder for visual config creation
  • Configuration templates library
  • Bulk operations
  • Configuration diff viewer
  • Export/import configurations
  • Real-time collaboration
  • Audit log viewer
  • Advanced search and filtering
  • Configuration validation preview
  • Integration with CI/CD pipelines

Technical Improvements

  • HTTP-only cookie authentication
  • Token refresh mechanism
  • WebSocket support for real-time updates
  • Advanced Monaco editor integration
  • Configuration schema validation
  • Offline support with service workers
  • Internationalization (i18n)
  • Accessibility (WCAG 2.1 AA)

📚 Related Documentation

🤝 Contributing

When contributing to the Web UI:

  1. Follow TypeScript best practices
  2. Write tests for new features
  3. Use Prettier for code formatting
  4. Update type definitions when API changes
  5. Document new components and hooks
  6. Ensure accessibility standards

📄 License

Apache License 2.0 - See LICENSE.md

Built with ❤️ for the NGINX Declarative API project