docker.recipes

Kong API Gateway

advanced

Kong API Gateway with PostgreSQL and Konga admin dashboard for API management.

Overview

Kong is an open-source, cloud-native API gateway built on top of NGINX that provides traffic control, security, analytics, and transformation capabilities for APIs and microservices. Originally developed by Mashape (now Kong Inc.) in 2015, Kong has become one of the most popular API gateways due to its plugin architecture, high performance, and extensive feature set for managing API traffic at scale. This deployment creates a complete Kong API management platform using four interconnected services: a PostgreSQL database (kong-database) for storing Kong's configuration, a migration service (kong-migration) that initializes the database schema, the Kong gateway itself handling API traffic, and Konga providing a web-based administrative interface. The stack includes proper health checks and dependency management to ensure services start in the correct order, with Kong's database migrations completing before the gateway starts. This configuration is ideal for organizations implementing microservices architectures, API-first development strategies, or those needing centralized API management with advanced features like rate limiting, authentication, and request transformation. The inclusion of Konga makes this particularly valuable for teams who prefer visual administration over command-line API management, while the PostgreSQL backend ensures Kong's configuration persists and can handle enterprise-scale API traffic.

Key Features

  • Plugin-based architecture with over 50 official plugins for authentication, security, traffic control, and analytics
  • Declarative configuration support allowing GitOps-style API management through YAML files
  • Advanced rate limiting with multiple algorithms including sliding window, fixed window, and leaky bucket
  • Built-in support for multiple authentication methods including JWT, OAuth 2.0, LDAP, and API keys
  • Request and response transformation capabilities with custom headers, body modification, and routing rules
  • Konga web dashboard for visual API management, service discovery, and plugin configuration
  • Real-time API analytics and logging with structured output for integration with monitoring systems
  • Load balancing with health checks, circuit breakers, and automatic failover for upstream services

Common Use Cases

  • 1Microservices API gateway for containerized applications requiring centralized traffic management
  • 2Enterprise API management platform with role-based access control and audit trails
  • 3E-commerce platforms needing rate limiting, API key management, and payment gateway integration
  • 4SaaS applications requiring multi-tenant API access with quotas and billing integration
  • 5Mobile backend services with JWT authentication, CORS handling, and request throttling
  • 6Legacy system modernization using Kong as a facade for gradual API migration
  • 7Development and staging environments where teams need visual API testing and configuration management

Prerequisites

  • Docker Engine 20.10+ and Docker Compose V2 for proper health check and dependency support
  • Minimum 2GB RAM allocated to Docker (Kong requires 512MB, PostgreSQL 256MB, plus overhead)
  • Available ports 8000 (Kong proxy), 8001 (Kong admin), 8443/8444 (HTTPS), and 1337 (Konga)
  • Environment variables KONG_PG_PASSWORD and KONGA_TOKEN_SECRET configured in .env file
  • Basic understanding of API gateway concepts, HTTP proxying, and PostgreSQL administration
  • Familiarity with Kong's plugin system and REST API for advanced configuration management

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

docker-compose.yml

docker-compose.yml
1services: 
2  kong-database: 
3    image: postgres:16-alpine
4    container_name: kong-database
5    environment: 
6      - POSTGRES_USER=kong
7      - POSTGRES_DB=kong
8      - POSTGRES_PASSWORD=${KONG_PG_PASSWORD}
9    volumes: 
10      - kong_data:/var/lib/postgresql/data
11    healthcheck: 
12      test: ["CMD-SHELL", "pg_isready -U kong"]
13      interval: 10s
14      timeout: 5s
15      retries: 5
16    networks: 
17      - kong-network
18
19  kong-migration: 
20    image: kong:3.5
21    command: kong migrations bootstrap
22    environment: 
23      - KONG_DATABASE=postgres
24      - KONG_PG_HOST=kong-database
25      - KONG_PG_USER=kong
26      - KONG_PG_PASSWORD=${KONG_PG_PASSWORD}
27    depends_on: 
28      kong-database: 
29        condition: service_healthy
30    networks: 
31      - kong-network
32
33  kong: 
34    image: kong:3.5
35    container_name: kong
36    environment: 
37      - KONG_DATABASE=postgres
38      - KONG_PG_HOST=kong-database
39      - KONG_PG_USER=kong
40      - KONG_PG_PASSWORD=${KONG_PG_PASSWORD}
41      - KONG_PROXY_ACCESS_LOG=/dev/stdout
42      - KONG_ADMIN_ACCESS_LOG=/dev/stdout
43      - KONG_PROXY_ERROR_LOG=/dev/stderr
44      - KONG_ADMIN_ERROR_LOG=/dev/stderr
45      - KONG_ADMIN_LISTEN=0.0.0.0:8001
46    ports: 
47      - "8000:8000"
48      - "8443:8443"
49      - "8001:8001"
50      - "8444:8444"
51    depends_on: 
52      kong-migration: 
53        condition: service_completed_successfully
54    healthcheck: 
55      test: ["CMD", "kong", "health"]
56      interval: 10s
57      timeout: 10s
58      retries: 10
59    networks: 
60      - kong-network
61
62  konga: 
63    image: pantsel/konga:latest
64    container_name: konga
65    environment: 
66      - NODE_ENV=production
67      - TOKEN_SECRET=${KONGA_TOKEN_SECRET}
68    ports: 
69      - "1337:1337"
70    depends_on: 
71      - kong
72    networks: 
73      - kong-network
74
75volumes: 
76  kong_data: 
77
78networks: 
79  kong-network: 
80    driver: bridge

.env Template

.env
1# Kong API Gateway
2KONG_PG_PASSWORD=kong_secure_password
3KONGA_TOKEN_SECRET=your-secret-token

Usage Notes

  1. 1Kong Admin API at http://localhost:8001
  2. 2Kong Proxy at http://localhost:8000
  3. 3Konga Dashboard at http://localhost:1337
  4. 4Connect Konga to http://kong:8001
  5. 5Supports plugins for auth, rate-limiting, etc.

Individual Services(4 services)

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

kong-database
kong-database:
  image: postgres:16-alpine
  container_name: kong-database
  environment:
    - POSTGRES_USER=kong
    - POSTGRES_DB=kong
    - POSTGRES_PASSWORD=${KONG_PG_PASSWORD}
  volumes:
    - kong_data:/var/lib/postgresql/data
  healthcheck:
    test:
      - CMD-SHELL
      - pg_isready -U kong
    interval: 10s
    timeout: 5s
    retries: 5
  networks:
    - kong-network
kong-migration
kong-migration:
  image: kong:3.5
  command: kong migrations bootstrap
  environment:
    - KONG_DATABASE=postgres
    - KONG_PG_HOST=kong-database
    - KONG_PG_USER=kong
    - KONG_PG_PASSWORD=${KONG_PG_PASSWORD}
  depends_on:
    kong-database:
      condition: service_healthy
  networks:
    - kong-network
kong
kong:
  image: kong:3.5
  container_name: kong
  environment:
    - KONG_DATABASE=postgres
    - KONG_PG_HOST=kong-database
    - KONG_PG_USER=kong
    - KONG_PG_PASSWORD=${KONG_PG_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
  ports:
    - "8000:8000"
    - "8443:8443"
    - "8001:8001"
    - "8444:8444"
  depends_on:
    kong-migration:
      condition: service_completed_successfully
  healthcheck:
    test:
      - CMD
      - kong
      - health
    interval: 10s
    timeout: 10s
    retries: 10
  networks:
    - kong-network
konga
konga:
  image: pantsel/konga:latest
  container_name: konga
  environment:
    - NODE_ENV=production
    - TOKEN_SECRET=${KONGA_TOKEN_SECRET}
  ports:
    - "1337:1337"
  depends_on:
    - kong
  networks:
    - kong-network

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  kong-database:
5    image: postgres:16-alpine
6    container_name: kong-database
7    environment:
8      - POSTGRES_USER=kong
9      - POSTGRES_DB=kong
10      - POSTGRES_PASSWORD=${KONG_PG_PASSWORD}
11    volumes:
12      - kong_data:/var/lib/postgresql/data
13    healthcheck:
14      test: ["CMD-SHELL", "pg_isready -U kong"]
15      interval: 10s
16      timeout: 5s
17      retries: 5
18    networks:
19      - kong-network
20
21  kong-migration:
22    image: kong:3.5
23    command: kong migrations bootstrap
24    environment:
25      - KONG_DATABASE=postgres
26      - KONG_PG_HOST=kong-database
27      - KONG_PG_USER=kong
28      - KONG_PG_PASSWORD=${KONG_PG_PASSWORD}
29    depends_on:
30      kong-database:
31        condition: service_healthy
32    networks:
33      - kong-network
34
35  kong:
36    image: kong:3.5
37    container_name: kong
38    environment:
39      - KONG_DATABASE=postgres
40      - KONG_PG_HOST=kong-database
41      - KONG_PG_USER=kong
42      - KONG_PG_PASSWORD=${KONG_PG_PASSWORD}
43      - KONG_PROXY_ACCESS_LOG=/dev/stdout
44      - KONG_ADMIN_ACCESS_LOG=/dev/stdout
45      - KONG_PROXY_ERROR_LOG=/dev/stderr
46      - KONG_ADMIN_ERROR_LOG=/dev/stderr
47      - KONG_ADMIN_LISTEN=0.0.0.0:8001
48    ports:
49      - "8000:8000"
50      - "8443:8443"
51      - "8001:8001"
52      - "8444:8444"
53    depends_on:
54      kong-migration:
55        condition: service_completed_successfully
56    healthcheck:
57      test: ["CMD", "kong", "health"]
58      interval: 10s
59      timeout: 10s
60      retries: 10
61    networks:
62      - kong-network
63
64  konga:
65    image: pantsel/konga:latest
66    container_name: konga
67    environment:
68      - NODE_ENV=production
69      - TOKEN_SECRET=${KONGA_TOKEN_SECRET}
70    ports:
71      - "1337:1337"
72    depends_on:
73      - kong
74    networks:
75      - kong-network
76
77volumes:
78  kong_data:
79
80networks:
81  kong-network:
82    driver: bridge
83EOF
84
85# 2. Create the .env file
86cat > .env << 'EOF'
87# Kong API Gateway
88KONG_PG_PASSWORD=kong_secure_password
89KONGA_TOKEN_SECRET=your-secret-token
90EOF
91
92# 3. Start the services
93docker compose up -d
94
95# 4. View logs
96docker 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-postgres/run | bash

Troubleshooting

  • kong-migration fails with connection refused: Ensure kong-database health check passes before migration runs, check KONG_PG_PASSWORD environment variable matches
  • Kong admin API returns 404 errors: Verify KONG_ADMIN_LISTEN is set to 0.0.0.0:8001 and container port 8001 is properly exposed
  • Konga cannot connect to Kong: Use connection URL http://kong:8001 (internal Docker network name), not localhost:8001
  • Kong proxy returns 503 Service Temporarily Unavailable: No upstream services configured yet, add services and routes through Konga or Admin API
  • Database migration hangs indefinitely: Check PostgreSQL logs for connection limits or disk space issues, restart kong-database service if needed
  • Konga dashboard shows 'Invalid token' errors: Regenerate KONGA_TOKEN_SECRET environment variable and restart konga container

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

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

Components

kongkongapostgres

Tags

#kong#api-gateway#microservices#proxy#rate-limiting

Category

Web Servers & Reverse Proxies

Related Recipes

Ad Space