OpsCommand v1.0.0
Documentation website for the collaborative DevOps terminal
GitHub ↗
Docker Compose Kubernetes Socket.io MongoDB No changelog or tags

OpsCommand

OpsCommand is a collaborative DevOps workspace that combines team chat, a live ops terminal, a user dashboard, and Kubernetes-aware commands in one interface. This documentation is built directly from the repository's README, source files, manifests, and screenshots, so every claim here traces back to code or checked-in config.

Audience Engineering teams that want one browser surface for chat, operational commands, and cluster state.
Runtime shape React frontend, Express + Socket.io backend, MongoDB persistence, and Kubernetes integration through the client SDK.
Docs status Single-file site in docs/index.html, designed for GitHub Pages and local static preview.
Docs/Overview

Overview

OpsCommand unifies collaboration and Kubernetes operations. The frontend gives engineers a split workspace for chat and terminal commands, while the backend authenticates users, persists history, executes slash commands, scrapes cluster state, and publishes telemetry.

What it does

  • Real-time team chat over Socket.io.
  • Slash-command ops terminal for Kubernetes workflows.
  • JWT-based auth, profile updates, and persisted message history.

What it is for

  • Incident response and routine cluster work.
  • Engineering teams who need one workspace instead of several tools.
  • Local development with Docker Compose or Kubernetes/Skaffold.

What was read

  • README.md, requirements.md, project_report.md, system_modeling.md.
  • Backend and frontend source modules.
  • Kubernetes, monitoring, and GitHub Actions config.

Repository map

The list below covers the relevant non-ignored files discovered under the project root. Ignored directories such as .git, node_modules, dist, build, __pycache__, and .env are excluded on purpose.

Core, docs, and toolchain files 22 files
  • README.md
  • requirements.md
  • project_report.md
  • project_report.pdf
  • system_modeling.md
  • index.html (root redirect)
  • docker-compose.yml
  • skaffold.yaml
  • kind-config.yaml
  • .gitignore
  • .github/workflows/deploy-pages.yml
  • .github/workflows/ci.yaml
  • backend/package.json
  • backend/package-lock.json
  • frontend/package.json
  • frontend/package-lock.json
  • backend/Dockerfile
  • frontend/Dockerfile
  • frontend/README.md
  • frontend/index.html
  • frontend/eslint.config.js
  • frontend/vite.config.js
Backend source files ⚠️ needs docs
  • backend/server.js
  • backend/routes/auth.js
  • backend/config/passport.js
  • backend/middleware/auth.js
  • backend/models/User.js
  • backend/commands/clear.js
  • backend/commands/help.js
  • backend/commands/logs.js
  • backend/commands/restart.js
  • backend/commands/status.js
  • backend/commands/userlist.js
  • backend/commands/visualize.js
Frontend source files ⚠️ needs docs
  • frontend/src/main.jsx
  • frontend/src/App.jsx
  • frontend/src/config/runtime.js
  • frontend/src/components/Analytics.jsx
  • frontend/src/components/Dashboard.jsx
  • frontend/src/components/LoginScreen.jsx
  • frontend/src/components/OpsTerminal.jsx
  • frontend/src/components/ProfileSidebar.jsx
  • frontend/src/components/TeamChat.jsx
  • frontend/src/App.css
  • frontend/src/index.css
  • frontend/src/components/Analytics.css
  • frontend/src/components/Dashboard.css
  • frontend/src/components/LoginScreen.css
  • frontend/src/components/OpsTerminal.css
  • frontend/src/components/ProfileSidebar.css
  • frontend/src/components/TeamChat.css
Schema, deployment, and monitoring config 13 files
  • k8s/backend.yaml
  • k8s/configmap.yaml
  • k8s/frontend.yaml
  • k8s/ingress.yaml
  • k8s/mongo.yaml
  • k8s/monitoring.yaml
  • k8s/rbac.yaml
  • k8s/secret.yaml
  • monitoring/prometheus/prometheus.yml
  • monitoring/prometheus/alerts.yml
  • monitoring/grafana/provisioning/datasources/prometheus.yml
  • monitoring/grafana/provisioning/dashboards/dashboards.yml
  • monitoring/grafana/dashboards/opscommand-overview.json
Assets and media 4 files
  • assets/operations.png
  • assets/dashboard.png
  • frontend/src/assets/react.svg
  • frontend/public/vite.svg
OpsCommand operations view screenshot
Operations view: split chat and ops terminal with a unified command input.
OpsCommand dashboard view screenshot
Dashboard view: cluster health summary plus registered users table.
Docs/Quick Start

Quick Start

The quickest path to a working setup is Docker Compose. If you want the Kubernetes path, the manifests and Skaffold config are ready too.

1. Install dependencies

Install frontend and backend packages 
cd frontend
npm install

cd ../backend
npm install

2. Start the stack

Local Docker Compose workflow 
cd ..
docker-compose up

This brings up the frontend on http://localhost:5173, backend on http://localhost:4000, MongoDB on 27017, Prometheus on 9090, Grafana on 3000, and Node Exporter on 9100.

3. Sign in or register

The login screen talks to /api/auth/login and /api/auth/register, then stores the JWT in localStorage under ops_token.

4. Try your first commands

First working example in the ops terminal 
/help
/status
/visualize

Regular text goes to team chat, while anything starting with / becomes an ops command.

Tip: if you prefer Kubernetes, jump to the Guides section for the kind + skaffold path.
Docs/Architecture

Architecture

The design is intentionally small and direct: a React client talks to an Express backend by both REST and Socket.io, while the backend persists messages in MongoDB and reaches the Kubernetes API through the official client library.

Text diagram of the runtime layout 
Engineer
  │
  ▼
Browser ── REST/JWT ──► Express backend ──► MongoDB
  │                          │
  │                          ├──► Socket.io events (team chat + ops logs)
  │                          ├──► Kubernetes client-node API
  │                          └──► Dynamic command loader from backend/commands
  │
  └── WebSocket ─────────────► Real-time updates back to the UI

Key decisions visible in source

  • Commands are discovered at startup by reading backend/commands/*.js.
  • The frontend uses one input bar: slash-prefixed text becomes ops traffic; everything else is chat.
  • Auth state is JWT-based, while the code also keeps a separate passport session helper in source.
  • Prometheus metrics are exported from the backend on /metrics.

Flow in plain English

  • Login or register in the browser.
  • Receive a token and store it locally.
  • Open the split workspace and send chat or ops commands.
  • Render live results, history, dashboard data, and monitoring links.
Note: the repository includes both JWT auth routes and a Passport GitHub strategy helper. The live backend entrypoint currently wires JWT auth into the dashboard endpoint and profile routes.
Docs/API Reference

API Reference

This reference stays strictly inside the code that exists. If a module is lightly commented or not wired into the current runtime path, that is called out directly.

backend/server.js ⚠️ needs docs
Entry point Express Socket.io MongoDB Prometheus Kubernetes client

Purpose: boot the HTTP server, connect to MongoDB with retry logic, configure the Kubernetes clients, mount auth routes, expose metrics, and wire the live chat / ops command transport.

Surface Behavior Notes
GET /metrics Returns Prometheus metrics from the local registry. Includes default Node metrics plus custom command counters and latency histogram.
GET /api/dashboard/overview Requires Bearer token, then returns running pod counts and user list. Uses verifyToken from backend/routes/auth.js.
Socket events team-message, ops-command, and legacy send_message. Messages are persisted to MongoDB and rebroadcast as chat or ops log events.

Side effects: the module opens the server on 0.0.0.0:4000, starts a MongoDB connection attempt, loads commands dynamically, and emits operational logs to connected clients.

backend/routes/auth.js ⚠️ needs docs
JWT Register / Login / Me / Profile Exports router + verifyToken
Route Request Response
POST /api/auth/register { username, displayName, password } 201 { token, user }; validates required fields and minimum password length.
POST /api/auth/login { username, password } { token, user }; rejects missing or invalid credentials.
GET /api/auth/me Bearer token in Authorization header. { user }; returns 401 when no token or token is invalid.
PUT /api/auth/profile { displayName?, currentPassword?, newPassword? } plus Bearer token. { token, user }; re-signs the token after updates.
  • Token expiry: 7d.
  • JWT payload: { id, username, displayName }.
  • Default secret fallback in source: opscommand-secret-key-change-in-production.
backend/models/User.js ⚠️ needs docs
Mongoose model Password hashing Role-based defaults
Field / Method Signature or shape Notes
username String, required, unique, 3-30 chars. Trimmed before save.
displayName String, required, 1-50 chars. Trimmed before save.
password String, required, at least 6 chars. Hashed in a pre('save') hook with bcrypt salt rounds of 10.
role / permissions Role enum: admin, engineer, viewer. Default role is engineer; permissions are inferred from role when the array is empty.
comparePassword(candidatePassword) Instance method Returns bcrypt comparison result.
toJSON() Instance method Strips password from serialized output.
backend/middleware/auth.js ⚠️ needs docs
Session helper Protected command list

This file exports session-oriented helpers and a command allowlist. It is present in source, but the active backend runtime currently uses JWT auth middleware in server.js rather than Express session auth.

  • isAuthenticated(req, res, next) — calls req.isAuthenticated().
  • getSocketUser(socket) — reads socket.request.session?.passport?.user.
  • protectedCommands — ['/restart', '/execute'].
  • isProtectedCommand(commandName) — membership test for the allowlist.
backend/config/passport.js ⚠️ needs docs
Passport GitHub strategy Session serializer

Configures passport-github2 with GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, and GITHUB_CALLBACK_URL, then serializes a simple user object from the GitHub profile.

Note: this helper exists in source, but it is not imported by the current backend/server.js entrypoint. The backend package manifest in this repo also does not list Passport-related dependencies.
backend/commands/*.js ⚠️ needs docs
Dynamic plugins Each exports { name, description, execute }
Command Signature What it does
/clear execute(data, context) Broadcasts clear-ops-terminal and confirms terminal reset.
/help execute(data, context) Builds a live help message from the loaded command map.
/logs <pod-name> execute(data, context) Reads the last 20 log lines from a pod in the default namespace.
/restart <deployment-name> execute(data, context) Reads and replaces the deployment, stamping kubectl.kubernetes.io/restartedAt.
/status execute(data, context) Counts total and running pods in the default namespace.
/userlist execute(data, context) Queries MongoDB users and renders an ASCII table of usernames, roles, and permissions.
/visualize execute(data, context) Produces an ASCII health board for backend uptime, pod status, and prior failures.

The command loader in server.js reads every .js file in this folder, inserts it into a map keyed by command.name, and dispatches via the shared handleCommand() helper.

frontend/src/App.jsx ⚠️ needs docs
Default export: App Creates shared socket at module load Auth gate

Orchestrates the login flow, profile sidebar, top bar, page switching, and the unified input bar that routes slash commands to the ops terminal. It imports the backend URL from frontend/src/config/runtime.js and opens the Socket.io client immediately.

  • State: user, token, auth loading, profile panel, terminal collapse, active page, socket connection.
  • Auth bootstrap: reads ops_token from localStorage and validates it with /api/auth/me.
  • Unified send rule: messages starting with / emit ops-command; all others emit team-message.
frontend/src/components/Dashboard.jsx ⚠️ needs docs
Default export: Dashboard({ token }) Fetches /api/dashboard/overview

Renders a donut chart of running pods by service and a user table. It calls the authenticated dashboard endpoint, then normalizes the response into ops-backend, ops-frontend, and ops-mongo counts.

frontend/src/components/Analytics.jsx ⚠️ needs docs
Default export: Analytics() Uses runtime URLs

Presents launch targets for Grafana, Prometheus, and backend metrics. The selected destination updates the visible panel and opens the target in a new tab.

frontend/src/components/LoginScreen.jsx ⚠️ needs docs
Default export: LoginScreen({ onLogin }) Register / login UI

Handles both register and login flows. Successful auth writes the token and user payload to localStorage, then hands control back to App.

frontend/src/components/OpsTerminal.jsx partly documented
Default export: OpsTerminal({ socket, isConnected, myId }) Listens for ops-log

The right-side terminal keeps a log history, pretty-prints JSON when it can, classifies severity from text content, and listens for load_ops_history, ops-log, and clear-ops-terminal.

  • looksLikeCodeBlock(text) — detects JSON-like or multi-line structured output.
  • classifyMessage(text) — returns info, success, warning, or error.
  • tryPrettyJson(text) — returns formatted JSON or null.
frontend/src/components/TeamChat.jsx partly documented
Default export: TeamChat({ socket, isConnected, myId }) Listens for team-message

The left-side chat panel loads persisted chat history, appends live messages, and derives avatar initials and colors from sender names.

  • initials(name) — turns sender names into short avatar text.
  • avatarColor(name) — stable pseudo-random color selection.
  • formatTime(timestamp) — renders message timestamps for the bubble footer.
frontend/src/components/ProfileSidebar.jsx ⚠️ needs docs
Default export: ProfileSidebar({ user, token, onUpdate, onLogout, open, onClose })

Slide-in profile editor for changing display name and password, with token refresh after a successful update and a local logout path.

frontend/src/config/runtime.js ⚠️ needs docs
Exports BACKEND_URL, GRAFANA_URL, PROMETHEUS_URL

Resolves runtime URLs from Vite environment variables or the current host. Local development defaults to localhost, while ingress deployments reuse the current host and append the Grafana or Prometheus path prefix.

frontend/src/main.jsx ⚠️ needs docs
Mounts App React StrictMode

Bootstraps the React root at #root and renders App inside StrictMode.

Docs/Configuration

Configuration

This section covers the knobs present in the source: environment variables, Kubernetes manifests, monitoring config, and the deployment helpers used by Docker Compose, Skaffold, and GitHub Actions.

Environment variables

Key Used by Type / default What it controls
PORT Backend server, Docker Compose, K8s ConfigMap String / 4000 HTTP port for the backend entrypoint.
MONGO_URI Backend, Docker Compose, K8s Secret String / mongodb://localhost:27017/opscommand in source MongoDB connection string used by Mongoose.
JWT_SECRET backend/routes/auth.js String / opscommand-secret-key-change-in-production Signs and verifies auth tokens.
GITHUB_CLIENT_ID backend/config/passport.js String / no default GitHub OAuth client ID for the Passport helper.
GITHUB_CLIENT_SECRET backend/config/passport.js String / no default GitHub OAuth client secret for the Passport helper.
GITHUB_CALLBACK_URL backend/config/passport.js String / http://localhost:4000/auth/github/callback Callback URL for the GitHub Passport strategy.
VITE_BACKEND_URL frontend/src/config/runtime.js String / derived from host Overrides the backend API base URL.
VITE_GRAFANA_URL frontend/src/config/runtime.js, frontend deployment String / derived from host or http://localhost:3000 Controls the analytics link target for Grafana.
VITE_PROMETHEUS_URL frontend/src/config/runtime.js, frontend deployment String / derived from host or http://localhost:9090 Controls the analytics link target for Prometheus.

Deployment and infrastructure config

Docker Compose

  • app service builds ./backend and maps port 4000.
  • frontend service builds ./frontend and maps port 5173.
  • mongo, prometheus, grafana, and node-exporter are included in the stack.
  • Grafana admin defaults to admin / admin.

Skaffold and kind

  • skaffold.yaml builds backend and frontend artifacts locally.
  • Port forwards are configured for 5173, 4000, 9090, and 3000.
  • kind-config.yaml enables ingress-ready control-plane port mappings for 80 and 443.

Kubernetes

  • k8s/backend.yaml deploys ops-backend with two replicas and opsbot-sa.
  • k8s/frontend.yaml deploys ops-frontend and exposes a NodePort service.
  • k8s/mongo.yaml provisions a PVC and MongoDB deployment.
  • k8s/ingress.yaml routes /socket.io, /api, and / for opscommand.local.

Monitoring

  • Prometheus scrapes the backend at /metrics.
  • Alert rules track high error rate and p95 latency.
  • Grafana is provisioned with a Prometheus datasource and the OpsCommand Monitoring dashboard.
File Key values What it means
k8s/rbac.yaml opsbot-sa, opsbot-role, opsbot-rolebinding Read-only pod access plus deployment patch/update permissions.
k8s/secret.yaml Base64 encoded MONGO_URI Points K8s workloads at mongodb://mongo-service:27017/opscommand.
monitoring/prometheus/prometheus.yml 5s scrape interval, 5s evaluation interval Scrapes Prometheus itself, the backend, and node-exporter.
monitoring/prometheus/alerts.yml Error rate > 20%, p95 latency > 1s Matches the alert rules also embedded in k8s/monitoring.yaml.
Docs/Guides

Guides

These are the three workflows that show up most clearly in the codebase: auth and profile updates, day-to-day ops command use, and local/Kubernetes deployment.

Authenticate and manage your profile

  • Open the login screen and either register or sign in.
  • The frontend stores the token in localStorage and validates it with /api/auth/me.
  • Open the profile sidebar from the avatar to change your display name or password.
  • Password changes require the current password and a new password of at least 6 characters.

Operate the cluster

  • Use /help to discover the available commands.
  • Use /status to see pod counts and /logs <pod> to inspect logs.
  • Use /restart <deployment> to stamp a rollout restart annotation.
  • Use /visualize for the ASCII health map and /userlist for role/permission inventory.

Deploy locally

  • Run the Docker Compose stack for the easiest local path.
  • Use kind create cluster --config kind-config.yaml for K8s.
  • Then run skaffold dev to build and deploy the frontend and backend images.
  • Use opscommand.local with the ingress controller for browser access.
Because there is no automated test suite in the repo surface, these guides are the most reliable way to validate the user-facing behavior by hand.
Docs/Examples

Examples

These snippets are copy-paste ready and mirror the commands and request shapes already present in the repository documentation or source.

Register a user

POST /api/auth/register 
curl -X POST http://localhost:4000/api/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"username":"jdoe","displayName":"Jane Doe","password":"secret123"}'

Log in and fetch the current user

Login then validate the token 
TOKEN=$(curl -s -X POST http://localhost:4000/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"jdoe","password":"secret123"}' | jq -r .token)

curl http://localhost:4000/api/auth/me \
  -H "Authorization: Bearer $TOKEN"

Monitoring queries from the README and dashboard

PromQL examples 
sum(rate(opscommand_commands_total[1m]))
100 * sum(rate(opscommand_commands_total{status="error"}[5m]))
    / clamp_min(sum(rate(opscommand_commands_total[5m])), 0.001)
histogram_quantile(0.95, sum(rate(opscommand_command_duration_seconds_bucket[5m])) by (le))

Local deployment commands

Docker Compose and Kubernetes paths 
docker-compose up

kind create cluster --config kind-config.yaml
skaffold dev

Slash commands from the ops terminal

Examples pulled from the command modules 
/help
/status
/logs backend-pod-name
/restart backend-deployment
/visualize
/userlist
/clear
Screenshot assets: operations.png and dashboard.png are used in the Overview section above.