Kong API Gateway

advanced

Enterprise API gateway with Kong, PostgreSQL, Konga admin UI, and Prometheus metrics.

Overview

Kong is a cloud-native API gateway built for high performance and extensibility, originally developed by Mashape (now Kong Inc.) in 2015. It serves as a traffic control layer for APIs and microservices, providing features like rate limiting, authentication, request transformation, and analytics through a robust plugin architecture. Kong's design philosophy centers around declarative configuration and horizontal scalability, making it a popular choice for organizations managing complex API ecosystems. This deployment creates a complete Kong API gateway environment with five interconnected services: a PostgreSQL database (kong-database) for storing Kong's configuration, a one-time migration service (kong-migration) that initializes the database schema, the main Kong gateway service exposing both proxy and admin APIs, Konga as a web-based administration interface, and Prometheus for metrics collection and monitoring. The stack uses PostgreSQL 15 Alpine for lightweight database operations, while Kong exposes multiple ports for different functions - 8000/8443 for proxy traffic, 8001/8444 for admin API access, and 8100 for status monitoring. This configuration is ideal for DevOps teams implementing API-first architectures, platform engineers building internal developer platforms, or organizations transitioning from monolithic to microservices architectures. The combination of Kong's powerful plugin ecosystem, Konga's intuitive management interface, and Prometheus monitoring creates a production-ready API management platform that can handle everything from simple request routing to complex authentication workflows and traffic shaping policies.

Key Features

Plugin-based architecture with 50+ official plugins for authentication, rate limiting, logging, and transformations
Dual-mode operation supporting both proxy traffic (8000/8443) and administrative control (8001/8444)
Declarative configuration management allowing GitOps workflows and infrastructure-as-code practices
Konga web UI providing visual service mapping, plugin configuration, and real-time traffic monitoring
PostgreSQL-backed persistence ensuring configuration consistency across Kong instance restarts and scaling
Prometheus metrics endpoint exposing detailed API gateway performance and usage statistics
Health check endpoints on Kong for automated container orchestration and load balancer integration
gRPC and HTTP/2 support with SSL termination capabilities for modern API protocols

Common Use Cases

1Microservices API gateway providing single entry point for distributed service architectures
2Legacy system modernization by adding authentication, rate limiting, and monitoring to existing APIs
3Multi-tenant SaaS platforms requiring per-customer rate limiting, authentication, and usage tracking
4Internal developer platforms centralizing API discovery, documentation, and access control
5E-commerce platforms managing payment gateway routing, fraud detection, and transaction monitoring
6IoT device management requiring device authentication, telemetry data transformation, and routing
7Mobile backend services needing request/response transformation and offline-capable caching strategies

Prerequisites

Docker Engine 20.10+ with Docker Compose V2 for proper healthcheck and dependency management
Minimum 2GB RAM allocation (512MB for Kong, 512MB for PostgreSQL, remainder for Konga and Prometheus)
Ports 1337, 8000-8001, 8443-8444, 8100, and 9090 available on the host system
Environment variables POSTGRES_USER and POSTGRES_PASSWORD configured for database access
Basic understanding of API gateway concepts, HTTP proxy behavior, and RESTful API management
Familiarity with Kong's Admin API or Konga UI for service and route configuration

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  kong-database: 
3    image: postgres:15-alpine
4    environment: 
5      POSTGRES_USER: ${POSTGRES_USER}
6      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
7      POSTGRES_DB: kong
8    volumes: 
9      - kong_db_data:/var/lib/postgresql/data
10    healthcheck: 
11      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
12      interval: 10s
13      timeout: 5s
14      retries: 5
15    networks: 
16      - kong-net
17    restart: unless-stopped
18
19  kong-migration: 
20    image: kong:latest
21    command: kong migrations bootstrap
22    environment: 
23      KONG_DATABASE: postgres
24      KONG_PG_HOST: kong-database
25      KONG_PG_USER: ${POSTGRES_USER}
26      KONG_PG_PASSWORD: ${POSTGRES_PASSWORD}
27    depends_on: 
28      kong-database: 
29        condition: service_healthy
30    networks: 
31      - kong-net
32    deploy: 
33      restart_policy: 
34        condition: on-failure
35        max_attempts: 3
36
37  kong: 
38    image: kong:latest
39    environment: 
40      KONG_DATABASE: postgres
41      KONG_PG_HOST: kong-database
42      KONG_PG_USER: ${POSTGRES_USER}
43      KONG_PG_PASSWORD: ${POSTGRES_PASSWORD}
44      KONG_PROXY_ACCESS_LOG: /dev/stdout
45      KONG_ADMIN_ACCESS_LOG: /dev/stdout
46      KONG_PROXY_ERROR_LOG: /dev/stderr
47      KONG_ADMIN_ERROR_LOG: /dev/stderr
48      KONG_ADMIN_LISTEN: 0.0.0.0:8001, 0.0.0.0:8444 ssl
49      KONG_STATUS_LISTEN: 0.0.0.0:8100
50    ports: 
51      - "8000:8000"
52      - "8443:8443"
53      - "8001:8001"
54      - "8444:8444"
55    depends_on: 
56      kong-database: 
57        condition: service_healthy
58    healthcheck: 
59      test: ["CMD", "kong", "health"]
60      interval: 10s
61      timeout: 10s
62      retries: 10
63    networks: 
64      - kong-net
65    restart: unless-stopped
66
67  konga: 
68    image: pantsel/konga:latest
69    environment: 
70      DB_ADAPTER: postgres
71      DB_HOST: kong-database
72      DB_USER: ${POSTGRES_USER}
73      DB_PASSWORD: ${POSTGRES_PASSWORD}
74      DB_DATABASE: konga
75      NODE_ENV: production
76    ports: 
77      - "1337:1337"
78    depends_on: 
79      - kong
80    networks: 
81      - kong-net
82    restart: unless-stopped
83
84  prometheus: 
85    image: prom/prometheus:latest
86    ports: 
87      - "9090:9090"
88    volumes: 
89      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
90      - prometheus_data:/prometheus
91    networks: 
92      - kong-net
93    restart: unless-stopped
94
95volumes: 
96  kong_db_data: 
97  prometheus_data: 
98
99networks: 
100  kong-net: 
101    driver: bridge

.env Template

.env

1# PostgreSQL
2POSTGRES_USER=kong
3POSTGRES_PASSWORD=secure_postgres_password

Usage Notes

1Kong Admin at http://localhost:8001
2Kong Proxy at http://localhost:8000
3Konga UI at http://localhost:1337
4Enable plugins via Admin API or Konga

Individual Services(5 services)

Copy individual services to mix and match with your existing compose files.

kong-database

kong-database:
  image: postgres:15-alpine
  environment:
    POSTGRES_USER: ${POSTGRES_USER}
    POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    POSTGRES_DB: kong
  volumes:
    - kong_db_data:/var/lib/postgresql/data
  healthcheck:
    test:
      - CMD-SHELL
      - pg_isready -U ${POSTGRES_USER}
    interval: 10s
    timeout: 5s
    retries: 5
  networks:
    - kong-net
  restart: unless-stopped

kong-migration

kong-migration:
  image: kong:latest
  command: kong migrations bootstrap
  environment:
    KONG_DATABASE: postgres
    KONG_PG_HOST: kong-database
    KONG_PG_USER: ${POSTGRES_USER}
    KONG_PG_PASSWORD: ${POSTGRES_PASSWORD}
  depends_on:
    kong-database:
      condition: service_healthy
  networks:
    - kong-net
  deploy:
    restart_policy:
      condition: on-failure
      max_attempts: 3

kong

kong:
  image: kong:latest
  environment:
    KONG_DATABASE: postgres
    KONG_PG_HOST: kong-database
    KONG_PG_USER: ${POSTGRES_USER}
    KONG_PG_PASSWORD: ${POSTGRES_PASSWORD}
    KONG_PROXY_ACCESS_LOG: /dev/stdout
    KONG_ADMIN_ACCESS_LOG: /dev/stdout
    KONG_PROXY_ERROR_LOG: /dev/stderr
    KONG_ADMIN_ERROR_LOG: /dev/stderr
    KONG_ADMIN_LISTEN: 0.0.0.0:8001, 0.0.0.0:8444 ssl
    KONG_STATUS_LISTEN: 0.0.0.0:8100
  ports:
    - "8000:8000"
    - "8443:8443"
    - "8001:8001"
    - "8444:8444"
  depends_on:
    kong-database:
      condition: service_healthy
  healthcheck:
    test:
      - CMD
      - kong
      - health
    interval: 10s
    timeout: 10s
    retries: 10
  networks:
    - kong-net
  restart: unless-stopped

konga

konga:
  image: pantsel/konga:latest
  environment:
    DB_ADAPTER: postgres
    DB_HOST: kong-database
    DB_USER: ${POSTGRES_USER}
    DB_PASSWORD: ${POSTGRES_PASSWORD}
    DB_DATABASE: konga
    NODE_ENV: production
  ports:
    - "1337:1337"
  depends_on:
    - kong
  networks:
    - kong-net
  restart: unless-stopped

prometheus

prometheus:
  image: prom/prometheus:latest
  ports:
    - "9090:9090"
  volumes:
    - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
    - prometheus_data:/prometheus
  networks:
    - kong-net
  restart: unless-stopped

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  kong-database:
5    image: postgres:15-alpine
6    environment:
7      POSTGRES_USER: ${POSTGRES_USER}
8      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
9      POSTGRES_DB: kong
10    volumes:
11      - kong_db_data:/var/lib/postgresql/data
12    healthcheck:
13      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
14      interval: 10s
15      timeout: 5s
16      retries: 5
17    networks:
18      - kong-net
19    restart: unless-stopped
20
21  kong-migration:
22    image: kong:latest
23    command: kong migrations bootstrap
24    environment:
25      KONG_DATABASE: postgres
26      KONG_PG_HOST: kong-database
27      KONG_PG_USER: ${POSTGRES_USER}
28      KONG_PG_PASSWORD: ${POSTGRES_PASSWORD}
29    depends_on:
30      kong-database:
31        condition: service_healthy
32    networks:
33      - kong-net
34    deploy:
35      restart_policy:
36        condition: on-failure
37        max_attempts: 3
38
39  kong:
40    image: kong:latest
41    environment:
42      KONG_DATABASE: postgres
43      KONG_PG_HOST: kong-database
44      KONG_PG_USER: ${POSTGRES_USER}
45      KONG_PG_PASSWORD: ${POSTGRES_PASSWORD}
46      KONG_PROXY_ACCESS_LOG: /dev/stdout
47      KONG_ADMIN_ACCESS_LOG: /dev/stdout
48      KONG_PROXY_ERROR_LOG: /dev/stderr
49      KONG_ADMIN_ERROR_LOG: /dev/stderr
50      KONG_ADMIN_LISTEN: 0.0.0.0:8001, 0.0.0.0:8444 ssl
51      KONG_STATUS_LISTEN: 0.0.0.0:8100
52    ports:
53      - "8000:8000"
54      - "8443:8443"
55      - "8001:8001"
56      - "8444:8444"
57    depends_on:
58      kong-database:
59        condition: service_healthy
60    healthcheck:
61      test: ["CMD", "kong", "health"]
62      interval: 10s
63      timeout: 10s
64      retries: 10
65    networks:
66      - kong-net
67    restart: unless-stopped
68
69  konga:
70    image: pantsel/konga:latest
71    environment:
72      DB_ADAPTER: postgres
73      DB_HOST: kong-database
74      DB_USER: ${POSTGRES_USER}
75      DB_PASSWORD: ${POSTGRES_PASSWORD}
76      DB_DATABASE: konga
77      NODE_ENV: production
78    ports:
79      - "1337:1337"
80    depends_on:
81      - kong
82    networks:
83      - kong-net
84    restart: unless-stopped
85
86  prometheus:
87    image: prom/prometheus:latest
88    ports:
89      - "9090:9090"
90    volumes:
91      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
92      - prometheus_data:/prometheus
93    networks:
94      - kong-net
95    restart: unless-stopped
96
97volumes:
98  kong_db_data:
99  prometheus_data:
100
101networks:
102  kong-net:
103    driver: bridge
104EOF
105
106# 2. Create the .env file
107cat > .env << 'EOF'
108# PostgreSQL
109POSTGRES_USER=kong
110POSTGRES_PASSWORD=secure_postgres_password
111EOF
112
113# 3. Start the services
114docker compose up -d
115
116# 4. View logs
117docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/kong-gateway-stack/run | bash

Troubleshooting

Kong fails to start with 'database not ready': Verify kong-database container is healthy and accessible, check PostgreSQL credentials match between services
502 Bad Gateway on proxy requests: Ensure upstream services are reachable from kong container, verify service and route configuration in Admin API
Konga cannot connect to Kong Admin API: Confirm Kong admin interface is accessible on port 8001, check kong service health status
Plugin configuration not applying: Verify plugin is enabled on correct service/route scope, check Kong logs for plugin initialization errors
Prometheus metrics not collecting: Enable Kong's Prometheus plugin via Admin API, ensure kong status endpoint on port 8100 is accessible
Database migration failures: Check kong-migration service logs, ensure PostgreSQL accepts connections and has sufficient privileges for schema creation

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

kongkongapostgresqlprometheus

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download