# Gravitee API Management Platform

> Full API management with gateway, management API, and developer portal.

- Category: DevOps & CI/CD
- Difficulty: advanced
- Components: gravitee-gateway, gravitee-management, gravitee-portal, mongodb, elasticsearch
- Tags: gravitee, api-management, portal, gateway, analytics
- Source: https://docker.recipes/devops/gravitee-apim

## Overview

Gravitee API Management Platform is an open-source, full-featured API management solution that provides comprehensive API lifecycle management capabilities. Originally developed to address the complexity of modern API ecosystems, Gravitee offers a complete suite including an API gateway for traffic routing and policy enforcement, management APIs for configuration and administration, and a developer portal for API documentation and consumption. The platform has gained traction among organizations seeking an alternative to proprietary API management solutions while maintaining enterprise-grade features. This Docker stack combines Gravitee's core components with MongoDB for configuration and user data storage, plus Elasticsearch for analytics and logging. The gravitee-gateway handles API traffic routing, rate limiting, and security policies, while gravitee-management provides the REST APIs for administrative functions. The gravitee-console offers a web-based administrative interface, and gravitee-portal delivers a self-service developer experience for API discovery and consumption. MongoDB stores API definitions, user accounts, application registrations, and subscription data, while Elasticsearch powers the analytics dashboard, API usage metrics, and log aggregation. This combination creates a powerful API management platform suitable for organizations transitioning from monolithic architectures to microservices, companies building API-first products, or enterprises needing centralized API governance and security policies across distributed teams and services.

## Features

- API gateway with request/response transformation, routing policies, and traffic shaping capabilities
- Built-in rate limiting and quota management with MongoDB persistence for distributed enforcement
- OAuth2, JWT, API key authentication with customizable security policies per API endpoint
- Real-time API analytics and usage dashboards powered by Elasticsearch aggregations
- Developer portal with interactive API documentation, subscription management, and application registration
- Policy studio for creating custom request/response flows using drag-and-drop interface
- Multi-tenant organization support with role-based access control and environment separation
- API versioning and lifecycle management with deployment promotion workflows

## Use cases

- Enterprise API gateway for microservices architecture with centralized security and monitoring
- Public API monetization platform with developer onboarding and subscription management
- Internal API governance for large organizations with multiple development teams
- Legacy system modernization with API abstraction layer and gradual migration support
- Partner ecosystem management with controlled API access and usage analytics
- Regulatory compliance scenarios requiring detailed API audit trails and access logging
- Multi-cloud API strategy with consistent policy enforcement across environments

## Prerequisites

- Docker host with minimum 6GB RAM (2GB for Elasticsearch, 2GB for Gravitee components, 2GB for system)
- Available ports 8082-8085 for Gravitee services and 9200, 27017 for data stores
- MONGO_PASSWORD environment variable configured for MongoDB authentication
- Basic understanding of API management concepts like policies, plans, and applications
- Network connectivity for Gravitee license validation and plugin downloads
- SSD storage recommended for Elasticsearch performance and MongoDB operations

## docker-compose.yml

```yaml
services:
  mongodb:
    image: mongo:6
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_PASSWORD}
    volumes:
      - mongo_data:/data/db
    networks:
      - gravitee_net

  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:8.11.0
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
      - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
    volumes:
      - es_data:/usr/share/elasticsearch/data
    networks:
      - gravitee_net

  gravitee-gateway:
    image: graviteeio/apim-gateway:latest
    ports:
      - "8082:8082"
    environment:
      - gravitee_management_mongodb_uri=mongodb://admin:${MONGO_PASSWORD}@mongodb:27017/gravitee?authSource=admin
      - gravitee_ratelimit_mongodb_uri=mongodb://admin:${MONGO_PASSWORD}@mongodb:27017/gravitee?authSource=admin
      - gravitee_reporters_elasticsearch_endpoints_0=http://elasticsearch:9200
    depends_on:
      - mongodb
      - elasticsearch
    networks:
      - gravitee_net

  gravitee-management:
    image: graviteeio/apim-management-api:latest
    ports:
      - "8083:8083"
    environment:
      - gravitee_management_mongodb_uri=mongodb://admin:${MONGO_PASSWORD}@mongodb:27017/gravitee?authSource=admin
      - gravitee_analytics_elasticsearch_endpoints_0=http://elasticsearch:9200
    depends_on:
      - mongodb
      - elasticsearch
    networks:
      - gravitee_net

  gravitee-console:
    image: graviteeio/apim-management-ui:latest
    ports:
      - "8084:8080"
    environment:
      - MGMT_API_URL=http://localhost:8083/management/organizations/DEFAULT/environments/DEFAULT/
    depends_on:
      - gravitee-management
    networks:
      - gravitee_net

  gravitee-portal:
    image: graviteeio/apim-portal-ui:latest
    ports:
      - "8085:8080"
    environment:
      - PORTAL_API_URL=http://localhost:8083/portal/environments/DEFAULT
    depends_on:
      - gravitee-management
    networks:
      - gravitee_net

volumes:
  mongo_data:
  es_data:

networks:
  gravitee_net:
```

## .env

```bash
# Gravitee APIM
MONGO_PASSWORD=secure_mongo_password

# Gateway at http://localhost:8082
# Console at http://localhost:8084
# Portal at http://localhost:8085
# Default: admin/admin
```

## Usage notes

- Gateway at http://localhost:8082
- Admin Console at http://localhost:8084
- Developer Portal at http://localhost:8085
- Default credentials: admin/admin
- Full API lifecycle management

## Troubleshooting

- Gravitee Gateway returns 500 errors: Verify MongoDB connection string includes authSource=admin parameter
- Management Console shows 'Cannot connect to Management API': Ensure MGMT_API_URL uses localhost not container name for browser access
- Elasticsearch cluster health red: Increase vm.max_map_count on Docker host with 'sysctl -w vm.max_map_count=262144'
- Portal UI displays API documentation incorrectly: Check PORTAL_API_URL environment variable matches management API external URL
- MongoDB authentication failures: Confirm MONGO_PASSWORD environment variable matches across all Gravitee services
- Gateway policies not applying: Restart gravitee-gateway after policy changes and verify MongoDB connectivity for policy synchronization

