3023 Developer Onboarding 61358b2f

# ✅ Developer Onboarding Checklist

> Follow this checklist to set up your development environment, verify all features, and ensure consistent onboarding across ContextForge project.

---

## 🐳 VS Code Dev Container (Recommended)

The fastest way to get started is using the VS Code Dev Container, which provides a fully-configured development environment.

???+ check "Prerequisites"

    - [ ] **VS Code** with the [Dev Containers extension](https://code.visualstudio.com/docs/devcontainers/containers)
    - [ ] **Docker** or **Podman** installed and running locally

???+ check "Setup"

    1. Clone and open the repository:
        ```bash
        git clone https://github.com/ibm/mcp-context-forge.git
        cd mcp-context-forge
        code .
        ```

    2. VS Code will detect `.devcontainer` and prompt: **"Reopen in Container"**
       (or manually: ++ctrl+shift+p++ → **Dev Containers: Reopen in Container**)

    3. First-time build automatically:

        - Installs system packages & Python 3.11
        - Runs `make install-dev` to pull all dependencies
        - Executes tests to verify the toolchain

???+ check "Daily workflow inside container"

    ```bash
    make dev            # Dev server with hot reload (http://localhost:4444)
    make test           # Run test suite
    make lint           # Run all linters
    ```

???+ check "GitHub Codespaces (1-click cloud IDE)"

    No local Docker? Use Codespaces:

    1. Go to the repo → **Code ▸ Codespaces ▸ Create codespace on main**
    2. Wait for the container image to build in the cloud
    3. Develop using the same workflow above

---

## 🛠 Manual Environment Setup

If not using Dev Containers, set up manually:

???+ check "System prerequisites"

    - [ ] Python ≥ 3.11
    - [ ] 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 + Pyrefly extension
    - [ ] Optional: On Windows, install the WSL and Remote Development extensions

???+ check "Python tooling"

    - [ ] `pip install --upgrade pip`
    - [ ] `uv` and `uvx` installed - [install uv](https://github.com/astral-sh/uv)
    - [ ] `.venv` recreated with `make install-dev` (installs runtime + dev extras)

???+ 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 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 "Python unit tests"

    - [ ] `make test` passes all cases
    - [ ] `make coverage` generates coverage report

???+ check "UI automation (Playwright)"

    - [ ] `playwright install` (one-time browser setup)
    - [ ] `pytest tests/playwright/` passes
    - [ ] `pytest tests/playwright/ -k admin` validates Admin UI flows

???+ check "Load testing (Locust)"

    - [ ] `make testing-up` (containerized Locust + test services)
    - [ ] Or run Locust locally: `locust -f tests/loadtest/locustfile.py --host=http://localhost:4444`
    - [ ] Access dashboard at http://localhost:8089
    - [ ] Verify no errors under moderate load (50-100 users)

???+ check "Frontend linting"

    - [ ] `make eslint` - JavaScript linting
    - [ ] `make lint-web` - ESLint + HTMLHint + Stylelint
    - [ ] `make format-web` - Prettier formatting
    - [ ] Note: JS unit tests not yet implemented

---

## 🔐 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@example.com --exp 10080 --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