--- title: Contributing description: Contribute to MockServer -- explore the codebase architecture, build from source, run tests, and understand the module structure and CI/CD pipeline. layout: page pageOrder: 11 section: 'General' subsection: true sitemap: priority: 0.6 changefreq: 'monthly' lastmod: 2026-05-04T08:00:00+01:00 ---

MockServer is an open-source project that welcomes contributions and encourages users to understand its internals.

Whether you're looking to contribute code, report issues effectively, or simply understand how MockServer works under the hood, the developer documentation on GitHub provides comprehensive technical details about the codebase, infrastructure, and operations.

 

Developer Documentation on GitHub

The docs/ directory on GitHub contains detailed internal documentation organized into four main areas:

 

Code Architecture

Deep-dive documentation of MockServer's codebase, from high-level module structure down to individual subsystems:

Document Description
Code Overview Module hierarchy, dependency graph, package layout
Netty Pipeline Port unification, protocol detection, channel handlers, relay pattern
Request Processing Mock matching, proxy forwarding, action dispatch, WAR bridge
Event System LMAX Disruptor ring buffer, verification, persistence, observers
Dashboard UI React SPA, Redux state, WebSocket communication, data assembly
Domain Model Model hierarchy, matchers, codecs, OpenAPI support, configuration
TLS & Security BouncyCastle CA, SNI, mTLS, JWT auth, control plane security
Client & Integrations MockServerClient, JUnit 4/5, Spring, WebSocket callbacks
Memory Management Log entry and expectation memory analysis, default limit calculation, tuning guide
Metrics & Monitoring Prometheus metrics, memory monitoring, CSV export
 

Infrastructure

Documentation covering AWS accounts, CI/CD pipelines, container images, and Kubernetes deployment:

Document Description
AWS Infrastructure AWS accounts, Terraform IaC, EC2 agents, S3 hosting, CloudFront CDN
CI/CD Buildkite pipelines and GitHub Actions workflows
Docker Docker images, variants, multi-arch builds, and Compose examples
Helm & Kubernetes Helm charts, deployment templates, and Kind-based testing
 

Operations

Documentation about the build process, releases, dependencies, and the documentation website:

Document Description
Build System Maven configuration, profiles, plugins, and build scripts
Release Process End-to-end release workflow with diagrams
Security & Dependencies Java 11 compatibility policy, dependency version ceilings, and security scanning
Website Jekyll documentation site structure and publishing
Testing Test frameworks, module inventory, architecture, configuration, coverage gaps, CI execution
 

Additional Resources

Document Description
Architecture High-level architecture overview
Gaps & Recommendations Review of missing documentation and improvement areas
 

Contributing Code

If you're interested in contributing to MockServer:

  1. Start with the documentation — Read the documentation index to understand the codebase structure
  2. Review the architecture — Understand the module hierarchy and dependencies in the Code Overview
  3. Check the issue tracker — Browse open issues for good first contributions
  4. Follow conventions — Match the existing code style, test patterns, and commit message format used in the project
  5. Submit a pull request — Include tests and ensure all CI checks pass
 

Reporting Issues

To report bugs or request features:

  1. Check existing issues — Search the issue tracker to avoid duplicates
  2. Provide details — Include MockServer version, configuration, minimal reproduction steps, and expected vs actual behavior
  3. Enable debug logging — Use the debugging features to gather diagnostic information
  4. Submit on GitHub — Create a new issue with all the relevant details
 

Community