Merge pull request #134 from IBM/developer-onboarding-checklist

Added developer onboarding checklist

Author: crivetimihai

docs/docs/development/.pages

@@ -1,5 +1,6 @@
 nav:
   - index.md
+  - developer-onboarding.md
   - github.md
   - building.md
   - documentation.md

docs/docs/development/developer-onboarding.md

@@ -0,0 +1,186 @@
+# ✅ Developer Onboarding Checklist
+
+> Follow this checklist to set up your development environment, verify all features, and ensure consistent onboarding across the MCP Gateway project.
+
+---
+
+## 🛠 Environment Setup
+
+???+ check "System prerequisites"
+    - [ ] Python ≥ 3.10
+    - [ ] Node.js and npm, npx (used for testing with `supergateway` and the HTML/JS Admin UI)
+    - [ ] Docker, Docker Compose, and Podman
+    - [ ] Make, GitHub CLI (`gh`), `curl`, `jq`, `openssl`
+    - [ ] Optional: Visual Studio Code + Dev Containers extension (or WSL2 if on Windows)
+
+???+ check "Python tooling"
+    - [ ] `pip install --upgrade pip`
+    - [ ] `uv` and `uvenv` installed - [install uv](https://github.com/astral-sh/uv)
+    - [ ] `.venv` created with `make venv install install-dev`
+
+???+ check "Additional tools"
+    - [ ] `helm` installed for Kubernetes deployments ([Helm install docs](https://helm.sh/docs/intro/install/))
+    - [ ] Security tools in `$PATH`: `hadolint`, `dockle`, `trivy`, `osv-scanner`
+
+???+ check "Useful VS Code extensions"
+    - [ ] Python, Pylance
+    - [ ] YAML, Even Better TOML
+    - [ ] Docker, Dev Containers (useful on Windows)
+
+???+ check "GitHub setup"
+    - [ ] GitHub email configured in `git config`
+    - [ ] See [GitHub config guide](./github.md#16-personal-git-configuration-recommended)
+
+???+ check ".env configuration"
+    - [ ] Copy `.env.example` to `.env`
+    - [ ] Set various env variables, such as:
+        - `JWT_SECRET_KEY`
+        - `BASIC_AUTH_PASSWORD`
+---
+
+## 🔧 Makefile Targets
+
+???+ check "Local setup"
+    - [ ] `make check-env` (validates .env is complete)
+    - [ ] `make venv install install-dev serve`
+    - [ ] `make smoketest` runs and passes
+
+???+ check "Container builds"
+    - [ ] Docker: `make docker-prod docker-run-ssl-host compose-up`
+    - [ ] Podman: `make podman podman-prod podman-run-ssl-host`
+
+???+ check "Packaging"
+    - [ ] `make dist verify` builds packages
+    - [ ] `make devpi-install devpi-init devpi-start devpi-setup-user devpi-upload devpi-test`
+    - [ ] Install and test `mcpgateway` CLI locally
+
+???+ check "Minikube & Helm"
+    - [ ] `make helm-install minikube-install minikube-start minikube-k8s-apply helm-package helm-deploy`
+    - [ ] See [minikube deployment](deployment/minikube.md)
+
+---
+
+## 🧪 Testing
+
+???+ check "Code quality"
+    - [ ] `make lint`, `make lint-web`
+    - [ ] `make shell-linters-install`, `make shell-lint`
+    - [ ] `make hadolint` (Dockerfile linting)
+
+???+ check "Unit tests"
+    - [ ] `make test` passes all cases
+
+---
+
+## 🔐 Security
+
+???+ check "Vulnerability scans"
+    - [ ] Run:
+        ```bash
+        make hadolint dockle osv-scan trivy pip-audit
+        ```
+
+???+ check "SonarQube analysis"
+    - [ ] `make sonar-up-docker`
+    - [ ] `make sonar-submit-docker` — ensure no critical violations
+
+---
+
+## 🔑 JWT Authentication
+
+???+ check "Generate and use a Bearer token"
+    - [ ] Export a token with:
+        ```bash
+        export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin --exp 0 --secret my-test-key)
+        ```
+
+    - [ ] Verify authenticated API access:
+        ```bash
+        curl -k -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" https://localhost:4444/version | jq
+        ```
+
+---
+
+## 🤖 Client Integration
+
+???+ check "Run wrapper and test transports"
+    - [ ] Run: `python3 -m mcpgateway.wrapper` (stdio support)
+    - [ ] Test transports:
+        - Streamable HTTP
+        - Server-Sent Events (SSE)
+    - [ ] Optional: Integrate with Claude, Copilot, Continue ([usage guide](../using/index.md))
+
+---
+
+## 🧭 API Testing
+
+???+ check "Authentication required"
+    - [ ] Unauthenticated:
+        ```bash
+        curl http://localhost:4444/tools
+        # -> should return 401 Unauthorized
+        ```
+    - [ ] Authenticated:
+        ```bash
+        curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/version | jq
+        ```
+
+???+ check "Endpoint coverage"
+    - [ ] Confirm key routes:
+        - `/version`
+        - `/health`
+        - `/tools`
+        - `/servers`
+        - `/resources`
+        - `/prompts`
+        - `/gateways`
+    - [ ] Browse [Redoc docs](http://localhost:4444/redoc)
+
+---
+
+## 🖥 Admin UI
+
+???+ check "Login and diagnostics"
+    - [ ] Navigate to [`/admin`](http://localhost:4444/admin)
+    - [ ] Log in with Basic Auth credentials from `.env`
+    - [ ] `/version` shows healthy DB and Redis
+
+???+ check "CRUD verification"
+    - [ ] Create / edit / delete:
+        - Servers
+        - Tools
+        - Resources
+        - Prompts
+        - Gateways
+    - [ ] Toggle active/inactive switches
+    - [ ] JWT stored in `HttpOnly` cookie, no errors in DevTools Console
+
+???+ check "Metrics"
+    - [ ] Confirm latency and error rate display under load
+
+---
+
+## 📚 Documentation
+
+???+ check "Build and inspect docs"
+    - [ ] `cd docs && make venv serve`
+    - [ ] Open http://localhost:8000
+    - [ ] Confirm:
+        - `.pages` ordering
+        - nav structure
+        - working images
+        - Mermaid diagrams
+
+???+ check "Read and understand"
+    - [ ] `README.md` in root
+    - [ ] [Official docs site](https://ibm.github.io/mcp-context-forge/)
+    - [ ] [MkDocs Admonitions guide](https://squidfunk.github.io/mkdocs-material/reference/admonitions/)
+
+---
+
+## ✅ Final Review
+
+???+ check "Ready to contribute"
+    - [ ] All items checked
+    - [ ] PR description links to this checklist
+    - [ ] Stuck? Open a [discussion](https://github.com/your-repo/discussions) or issue