Skip to content

CONTRIBUTING.adoc

Latest commit

 

History

History
362 lines (251 loc) · 13.7 KB

CONTRIBUTING.adoc

File metadata and controls

362 lines (251 loc) · 13.7 KB

Contributing to Gravitee.io

You think Gravitee.io is awesome, and you’d like to contribute? Here are some guidelines that should help you get started.

Bootstrap Your Dev Environment

Overview

This section explains how to set up your environment to start contributing to APIM.

Prerequisites

You will need the following tools installed on your computer:

  • Java (JDK >= 17)

  • Maven

  • Docker

  • Node.js 22.12.x

  • Yarn 4.1.1 (preferably with NVM)

Tip
 The UI projects declare node: ^22.12 and packageManager: yarn@4.1.1 in their package.json files.

Get the project and prepare your workspace

Clone the project in your workspace
git clone https://github.com/gravitee-io/gravitee-api-management
Build APIM Management API and Gateway

The default build command is:

mvn clean install -T 2C

If you want to skip license validation, prettier checks, and tests, you can use:

mvn clean install -T 2C -DskipTests=true -Dskip.validation=true
Note
 This command will build create a distribution folder in the target folder of each module. These folders contain a full distribution of Management API and Gateway, with default plugins. These distribution folder should be used as the gravitee.home environment variable

To get a bundle with all the plugins (default, enterprise etc) you need to build the project with the following profile activated: bundle-default,bundle-dev. For instance:

mvn clean install -T 2C -P bundle-default,bundle-dev
Prepare APIM Console UI and Portal UI

First, be sure to have the correct version of node installed, there are .nvmrc files in the UI projects. If you’ve nvm installed, you can use nvm use to switch to the appropriate version of node.

Note
 Console and Portal Next are part of an Nx workspace at the root. Portal remains independent.

Then run yarn: - At the repository root for Console and Portal Next (Nx workspace) - In gravitee-api-management/gravitee-apim-portal-webui for Portal (independent project)

AI Agent Context (Docker Compose Full Stack)

This section is the source of truth for AI tools and should also be readable as a quickstart for humans.

Default behavior for AI tools:

  • For any "start/run/deploy" request, use the Docker Compose full-stack flow in docker/quick-setup/mongodb without asking which path to use.

  • Assume the user wants the whole stack deployment unless they explicitly say otherwise.

Full stack quickstart (MongoDB compose):

0) Setup environment (one-time) - Use correct Node.js version: nvm use (reads from .nvmrc) - Enable Corepack: corepack enable (recommended, included in Node.js 16.10+) - OR install Yarn globally: npm install -g yarn 1) (Optional) Build backend artifacts - mvn clean install -T 2C -DskipTests=true -Dskip.validation=true 2) Build console UI (Nx workspace at root) - yarn install - yarn console:build:prod 3) Build portal UI (independent project) - cd gravitee-apim-portal-webui && yarn install && yarn build && cd .. 4) Build local UI Docker images (from repo root) - docker build -t graviteeio/apim-management-ui:latest -f gravitee-apim-console-webui/docker/Dockerfile gravitee-apim-console-webui - docker build -t graviteeio/apim-portal-ui:latest -f gravitee-apim-portal-webui/docker/Dockerfile gravitee-apim-portal-webui 5) Start full stack with MongoDB compose - cd docker/quick-setup/mongodb - LICENSE_KEY=…​ docker compose up -d

Runtime endpoints (default compose):

Ports used by default (must be free):

  • 8082, 8083, 8084, 4100, 8025, 27017, 9200, 9300

Build workaround (host JDK 25/Lombok issues):

If the local Maven build fails with Lombok/compiler errors on JDK 25, build in a JDK 21 Maven container:

docker run --rm -u "$(id -u):$(id -g)" -e HOME=/home/maven -e MAVEN_CONFIG=/home/maven/.m2 -v "$HOME/.m2":/home/maven/.m2 -v "$PWD":/workspace -w /workspace maven:3.9.9-eclipse-temurin-21 mvn -pl gravitee-apim-rest-api/gravitee-apim-rest-api-standalone/gravitee-apim-rest-api-standalone-distribution -am package -DskipTests -Dskip.validation=true

To refresh the local Management API image used by docker/quick-setup/mongodb:

  • rm -rf gravitee-apim-rest-api/docker/distribution

  • cp -R gravitee-apim-rest-api/gravitee-apim-rest-api-standalone/gravitee-apim-rest-api-standalone-distribution/target/distribution gravitee-apim-rest-api/docker/distribution

  • docker build -t graviteeio/apim-management-api:latest gravitee-apim-rest-api/docker

  • cd docker/quick-setup/mongodb && docker compose up -d --no-deps --force-recreate management_api

Notes:

  • If LICENSE_KEY is not set, compose will warn and proceed without enterprise features.

  • Docker Desktop on Apple Silicon may warn on amd64 images (e.g., Mailhog); it usually still runs.

  • Node 25.x is not supported (odd-numbered); use Node 22.12.x.

  • Yarn setup: The package.json declares packageManager: yarn@4.1.1. Use Corepack (corepack enable) for automatic version management, or install Yarn globally. If neither is available, use the fallback: npx -y @yarnpkg/cli-dist@4.1.1 <command>.

  • If Docker pull/build fails, ensure Docker Desktop is running and you are logged in if required by the registry.

Environment checks:

  • docker --version and docker compose version

  • node -v (expect 22.12.x)

  • java -version (expect 17)

  • mvn -v (expect 3.9+)

  • git --version

Run Prerequisites

Before starting APIM Management API and Gateway, you need to start MongoDB and ElasticSearch.
You can, for instance, use docker.

MongoDB
docker run -p 27017:27017 --name local-mongo -d mongo:7
ElasticSearch
docker run -d --name local-es8 -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:8.10.4

Run Configuration

APIM Gateway (gravitee-apim-gateway)

IntelliJ configuration

The project includes by default the configuration Gateway - MongoDB to run the Gateway.

CLI Version

Run ./gravitee from the ${GRAVITEE_HOME}/bin directory.

Note
 ${GRAVITEE_HOME} refers to the target/distribution folder created before.

APIM Management API (gravitee-apim-rest-api)

IntelliJ configuration

The project includes by default the configuration Rest API - MongoDB to run the Rest API.

CLI Version

Run ./gravitee from the ${GRAVITEE_HOME}/bin directory.

Note
 ${GRAVITEE_HOME} refers to the target/distribution folder created before.

APIM Console (gravitee-apim-console-webui)

Note
 Console is part of an Nx workspace at the repository root.
IntelliJ configuration

Create a new Run configuration in IntelliJ:

  1. Click Run → Edit configurations → ✚ → npm.

  2. Name it as required.

  3. Choose package.json: gravitee-api-management/package.json (root workspace).

  4. Select Command: run.

  5. Select Script: console:serve.

Tip
 To run yarn from IntelliJ, you can duplicate this configuration and choose Command > Install.
CLI Version

Run yarn console:serve from the repository root to start the Console UI.

Alternative backends

  • yarn console:serve:apim-master - Connect to apim-master backend

  • yarn console:serve:apim-gko - Connect to apim-gko backend

APIM Portal (gravitee-apim-portal-webui)

IntelliJ Configuration

Create a new Run configuration in IntelliJ:

  1. Click Run → Edit configurations → ✚ → npm.

  2. Name it as required.

  3. Choose package.json: gravitee-api-management/gravitee-apim-portal-webui/package.json.

  4. Select Command: run.

  5. Select Script: serve.

Tip
 To run yarn from IntelliJ, you can duplicate this configuration and choose Command > Install.
CLI Version

Run yarn serve from the gravitee-api-management/gravitee-apim-portal-webui directory to start the UI.

Gamma Console (gravitee-gamma-control-plane-webui)

The Gamma Console is a micro-frontend host application that dynamically loads module plugins via Module Federation.

Prerequisites: Management API (Gamma enabled)

The Management API must expose the Gamma REST API at /gamma and load gamma-module plugins. By default, gamma.enabled is false in the standalone distribution config. Set it to true in the gravitee.yml used by your local API (for a built distribution, typically ${GRAVITEE_HOME}/config/gravitee.yml; the template lives under gravitee-apim-rest-api/gravitee-apim-rest-api-standalone/gravitee-apim-rest-api-standalone-distribution/src/main/resources/config/gravitee.yml).

Alternatively, you can enable Gamma via environment variable: GRAVITEE_GAMMA_ENABLED=true.

If the module list is empty or logs show Gamma is disabled, verify gamma.enabled is set.

Full local stack

  1. Start your usual Management API dependencies (for example MongoDB) and run the Management API on port 8083 (see APIM Management API (gravitee-apim-rest-api)) with Gamma enabled as described above.

  2. From the repository root, start the Gamma Console on port 4200:

    yarn gamma-console:serve

    The dev server proxies /gamma and /management requests to the backend at http://localhost:8083.

  3. Optional: when developing a module UI locally, run that module’s dev server and use DEV_MODULE_ENTRIES (see below).

Starting the Gamma Console
CLI Version

Run yarn gamma-console:serve from the repository root to start the Gamma Console on port 4200.

The dev server proxies /gamma and /management requests to the backend at http://localhost:8083.

Developing modules locally

By default, module UI assets are served by the backend from packaged plugins. During development, you can override specific modules to load from their local dev server instead, avoiding the need to rebuild the REST API.

The DEV_MODULE_ENTRIES keys must be each module’s plugin id (the id in that module’s plugin.properties), not the Nx project name. For example, the APIM module uses Nx project gravitee-gamma-module-apim but plugin id apim.

  1. Start the module dev server:

    yarn nx serve gravitee-gamma-module-apim

    This starts the module on port 3001 with hot-reload enabled.

  2. Start the Gamma Console with the DEV_MODULE_ENTRIES environment variable pointing to the local module:

    DEV_MODULE_ENTRIES="apim=http://localhost:3001/mf-manifest.json" yarn nx serve gamma-console

The format is <moduleId>=<manifest-url>. To override multiple modules, separate entries with commas:

DEV_MODULE_ENTRIES="apim=http://localhost:3001/mf-manifest.json,billing=http://localhost:3002/mf-manifest.json" yarn nx serve gravitee-gamma-control-plane-webui
Note
 The backend must still be running to serve the /modules listing endpoint and other APIs. Only the module assets are loaded from the local dev server.

Working with GitHub issues

We use GitHub issues to track bugs and enhancements. Found a bug in the source code? Want to propose new features or enhancements? You can help us by submitting an issue in our repository. Before submitting your issue, please search the issues archive to see if your question has already been answered.

Providing the following information will help us deal quickly with your issue:

  • Overview of the issue : describe the issue and why this is a bug for you.

  • Gravitee.io version(s) : possible regression ?

  • Browsers and Operating System : Linux/Windows/Docker ? Browser version for the UI, etc …​

  • You have stack trace, screenshots, logs ? add these to the issue’s description.

Submitting changes

Have you submitted an issue to the project and know how to fix it? You can contribute to the project by forking the repository and submitting your pull requests.

Before you submit your pull request consider the following guidelines:

  • Make your changes in a new git branch:

git checkout -b issue/<issue-id>-my-fix-branch master

Note : issue-id reference the id generated by GitHub.

  • Create your patch, including appropriate test cases.

  • Update the documentation if you create new features or think the documentation needs to be updated/completed.

  • Commit your changes using a descriptive Conventional Commit Message.

 git commit -a -m "feat: this is an example"

  • Build your changes locally to ensure all the tests pass:

mvn clean install

  • Push your branch to GitHub:

git push origin issue/<issue-id>-my-fix-branch

  • In GitHub, send a pull request to <gravitee-io/gravitee-api-management>:master.

  • If we suggest changes then:

    • Make the required updates.

    • Re-run the test suite to ensure tests are still passing.

    • Commit your changes to your branch (e.g. issue/<issue-id>-my-fix-branch).

    • Push the changes to your GitHub repository (this will update your Pull Request).

If the PR gets too outdated we may ask you to rebase and force push to update the PR:

git rebase master
git push origin issue/<issue-id>-my-fix-branch -f

That’s it! You’ve just contributed to the project, and we really appreciate it!

Further Information

You can find more detailed information about contributing in the Github guides.