|
| 1 | +# VMS Console |
| 2 | + |
| 3 | +A React web application built with IBM Carbon Design System, featuring a hierarchical navigation structure for managing network and composition resources. |
| 4 | + |
| 5 | +This package lives in the **skupper-X** monorepo at **`components/console`**. In the pnpm workspace it is named **`vms-console`** (`package.json`). |
| 6 | + |
| 7 | +## Features |
| 8 | + |
| 9 | +- **Carbon Design System**: Professional UI components with IBM's design language |
| 10 | +- **Hierarchical Navigation**: Organized menu structure with expandable sections |
| 11 | +- **Responsive Layout**: Mobile-friendly design using Carbon's grid system |
| 12 | +- **Custom Theming**: Configurable Carbon theme (currently using g100 dark theme) |
| 13 | +- **React Router**: Clean URL structure with nested routes |
| 14 | + |
| 15 | +## Project Structure |
| 16 | + |
| 17 | +``` |
| 18 | +components/console/ |
| 19 | +├── public/ # Static assets |
| 20 | +├── src/ |
| 21 | +│ ├── components/ |
| 22 | +│ │ ├── Header/ # Application header with Carbon UI Shell |
| 23 | +│ │ ├── Navigation/ # Side navigation with hierarchical menu |
| 24 | +│ │ └── OwnerGroupSelect/ # Owner group selector |
| 25 | +│ ├── pages/ |
| 26 | +│ │ ├── Dashboard/ # Main dashboard page |
| 27 | +│ │ ├── Backbones/ # Backbone configurations |
| 28 | +│ │ ├── VANs/ # Virtual Application Networks |
| 29 | +│ │ └── TLS/ # TLS certificates |
| 30 | +│ ├── tools/ |
| 31 | +│ │ └── watch.js # Watch code for live UI updates |
| 32 | +│ ├── theme/ # Custom Carbon theme configuration |
| 33 | +│ ├── App.jsx # Main application component and routes |
| 34 | +│ ├── App.simple.jsx |
| 35 | +│ ├── App.test.jsx |
| 36 | +│ ├── index.jsx # Application entry point |
| 37 | +│ └── index.css |
| 38 | +├── eslint.config.js |
| 39 | +├── index.html # Vite HTML entry |
| 40 | +├── vite.config.js |
| 41 | +├── package.json |
| 42 | +└── README.md |
| 43 | +``` |
| 44 | + |
| 45 | +Production builds emit static assets to **`dist/`** (Vite `outDir`). |
| 46 | + |
| 47 | +## Navigation structure |
| 48 | + |
| 49 | +- **Dashboard** — Main overview page |
| 50 | +- **Backbones** — Backbone configurations, sites, deployment |
| 51 | +- **VANs** — Virtual application networks |
| 52 | +- **TLS** — TLS certificate-related pages |
| 53 | + |
| 54 | +## Getting Started |
| 55 | + |
| 56 | +### Prerequisites |
| 57 | + |
| 58 | +- **Node.js** (current LTS recommended) |
| 59 | +- **pnpm** — this monorepo uses pnpm workspaces; use pnpm, not npm or yarn, for installs at the repo root |
| 60 | + |
| 61 | +### Installation |
| 62 | + |
| 63 | +From the **repository root**: |
| 64 | + |
| 65 | +```bash |
| 66 | +pnpm install |
| 67 | +pnpm --filter vms-console build |
| 68 | +``` |
| 69 | + |
| 70 | +`pnpm install` pulls in all workspace packages. `pnpm --filter vms-console build` runs Vite and writes the static bundle to **`components/console/dist`**. |
| 71 | + |
| 72 | +### Running the console (management controller) |
| 73 | + |
| 74 | +Run the **management controller** from **`components/management-controller`**. Its HTTP server loads [ViteExpress](https://github.com/szymmis/vite-express) so the same process serves the UI and the API: |
| 75 | + |
| 76 | +```bash |
| 77 | +cd components/management-controller |
| 78 | +node index.js |
| 79 | +``` |
| 80 | + |
| 81 | +**`NODE_ENV`** selects how the UI is served: |
| 82 | + |
| 83 | +- **`production`** — serve the **prebuilt static files** from `components/console/dist`. Run `pnpm --filter vms-console build` whenever you change the console so `dist` is up to date. |
| 84 | +- **Anything else** (e.g. **`development`** or unset) — run the **Vite dev server** inside the controller process: **HMR** and live reload over WebSockets, while API routes still go through the same Express app. |
| 85 | + |
| 86 | +**NOTE:** Running `pnpm dev` in `components/console` starts an isolated Vite dev server without the management API, so the UI **cannot talk to the backend** and will appear broken. |
| 87 | + |
| 88 | +### Lint |
| 89 | + |
| 90 | +```bash |
| 91 | +pnpm --filter vms-console lint |
| 92 | +``` |
| 93 | + |
| 94 | +## Dependencies |
| 95 | + |
| 96 | +- **react** & **react-dom**: Core React libraries |
| 97 | +- **react-router-dom**: Client-side routing |
| 98 | +- **@carbon/react**: Carbon Design System React components |
| 99 | +- **@carbon/icons-react**: Carbon icon library |
| 100 | +- **sass**: CSS preprocessor for Carbon styles |
| 101 | +- **vite**: Dev server and production bundling |
| 102 | + |
| 103 | +## Customization |
| 104 | + |
| 105 | +### Theme Configuration |
| 106 | + |
| 107 | +The Carbon theme can be customized in `src/theme/theme.scss`. Currently using the g100 (dark) theme. Available themes: |
| 108 | +- `white` - Light theme |
| 109 | +- `g10` - Light gray theme |
| 110 | +- `g90` - Dark gray theme |
| 111 | +- `g100` - Dark theme (current) |
| 112 | + |
| 113 | +To change the theme, modify the `$theme` parameter in `src/theme/theme.scss`: |
| 114 | +```scss |
| 115 | +@use '@carbon/react/scss/theme' with ( |
| 116 | + $theme: themes.$white // Change to desired theme |
| 117 | +); |
| 118 | +``` |
| 119 | + |
| 120 | +### Adding New Pages |
| 121 | + |
| 122 | +1. Create a new component in `src/pages/` |
| 123 | +2. Import and add a route in `src/App.jsx` |
| 124 | +3. Add navigation link in `src/components/Navigation/Navigation.jsx` |
| 125 | + |
| 126 | +## Development Status |
| 127 | + |
| 128 | +All core features are implemented: |
| 129 | +- ✅ Project initialization |
| 130 | +- ✅ Carbon Design System integration |
| 131 | +- ✅ Navigation structure |
| 132 | +- ✅ All page components with blank panels |
| 133 | +- ✅ Routing configuration |
| 134 | +- ✅ Custom theme setup |
| 135 | +- ✅ Responsive layout |
| 136 | + |
| 137 | +## Future Development |
| 138 | + |
| 139 | +Each page includes a blank panel ready for content development: |
| 140 | +- Dashboard metrics and widgets |
| 141 | +- Network configuration interfaces |
| 142 | +- TLS certificate management |
| 143 | +- Composition library browser |
| 144 | +- Application deployment tools |
| 145 | + |
| 146 | +## Browser Support |
| 147 | + |
| 148 | +Supports all modern browsers: |
| 149 | +- Chrome (latest) |
| 150 | +- Firefox (latest) |
| 151 | +- Safari (latest) |
| 152 | +- Edge (latest) |
| 153 | + |
| 154 | +## License |
| 155 | + |
| 156 | +This project is part of the VMS Console application. |
| 157 | + |
| 158 | +## Contributing |
| 159 | + |
| 160 | +When adding new features: |
| 161 | +1. Follow Carbon Design System guidelines |
| 162 | +2. Maintain consistent component structure |
| 163 | +3. Update navigation as needed |
| 164 | +4. Test responsive behavior |
| 165 | +5. Update this README |
| 166 | + |
| 167 | +## Resources |
| 168 | + |
| 169 | +- [Carbon Design System](https://carbondesignsystem.com/) |
| 170 | +- [Carbon React Components](https://react.carbondesignsystem.com/) |
| 171 | +- [React Router Documentation](https://reactrouter.com/) |
| 172 | +- [Vite](https://vite.dev/) |
0 commit comments