Atlassian uses cookies to improve your browsing experience, perform analytics and research, and conduct advertising. Accept all cookies to indicate that you agree to our use of cookies on your device. Atlassian cookies and tracking notice, (opens new window)
Before you begin, ensure your system meets the following requirements:
Operating System: Ubuntu 24.04 (or a compatible Debian-based distribution).
User Privileges: A user account with sudo access.
Docker: Required to build a custom Docker image.
2. Clone the Kong Gateway Repository
Start by cloning the Kong Gateway source code from its official GitHub repository.
git clone https://github.com/Kong/kong.git
cd kong
3. Install System Dependencies
Kong and its build tools (Bazel/Bazelisk) require several system packages, including compilers, development libraries, and utility tools. Install them using apt.
Bazelisk is the recommended way to manage Bazel versions. It automatically downloads the correct Bazel version required by your Kong project.
# Download the latest Bazelisk release for Linux AMD64
sudo curl -L https://github.com/bazelbuild/bazelisk/releases/latest/download/bazelisk-linux-amd64 -o /usr/local/bin/bazel
# Make Bazelisk executable
sudo chmod +x /usr/local/bin/bazel
# Verify the installation and trigger Bazelisk to download the appropriate Bazel version
bazel version
5. Install GitHub CLI (gh)
The GitHub CLI (gh) is a powerful tool for interacting with GitHub directly from your terminal. While not strictly required for building Kong, it's often useful in a development workflow.
This step is crucial for building the Docker image as it relies on the generated .deb package. This command builds the Debian package (.deb) which will contain the compiled Kong Gateway and its dependencies. The .deb package will be located in the bazel-bin/pkg/ directory.
Move the generated Debian package to the Docker build context:
mv bazel-bin/pkg/kong.amd64.deb .
Create a Dockerfile: Create a file named Dockerfile in the current directory (kong repository root) with the following content. This Dockerfile is based on the official Kong Docker builds.
FROM ubuntu:24.04
COPY kong.amd64.deb /tmp/kong.deb
RUN set -ex; \
apt-get update \
&& apt-get install --yes /tmp/kong.deb \
&& rm -rf /var/lib/apt/lists/* \
&& rm -rf /tmp/kong.deb \
&& chown kong:0 /usr/local/bin/kong \
&& chown -R kong:0 /usr/local/kong \
&& ln -s /usr/local/openresty/luajit/bin/luajit /usr/local/bin/luajit \
&& ln -s /usr/local/openresty/luajit/bin/luajit /usr/local/bin/lua \
&& ln -s /usr/local/openresty/nginx/sbin/nginx /usr/local/bin/nginx \
&& kong version
COPY docker-entrypoint.sh /docker-entrypoint.sh
USER kong
ENTRYPOINT ["/docker-entrypoint.sh"]
EXPOSE 8000 8443 8001 8444 8002 8445 8003 8446 8004 8447
STOPSIGNAL SIGQUIT
HEALTHCHECK --interval=10s --timeout=10s --retries=10 CMD kong health
CMD ["kong", "docker-start"]
Build the Docker image: Run the following command in the kong repository root (where your Dockerfile, docker-entrypoint.sh, and kong.amd64.deb are located).
This command will run your custom kong-eureka image and execute kong version inside it, performing a sanity check of the successful build and packaging. The output will look like:
3.10.0
Running and testing Kong Gateway docker image
1. Run Kong with docker-compose
1.1 Create a docker-compose.yml file: Place the following content into a file named docker-compose.yml in your chosen directory.
volumes:
kong_db_data: {} # Named volume to persist Postgres data across container restarts
networks:
kong-net: # Custom bridge network for isolated Kong and Postgres communication
driver: bridge
# Common environment variables used by Kong services (bootstrap and CP)
x-kong-config: &kong-env
KONG_DATABASE: postgres # Use Postgres as the backing database
KONG_PG_HOST: kong-database # Hostname of the Postgres service
KONG_PG_DATABASE: kong # Name of the database to connect to
KONG_PG_USER: kong # Database username
KONG_PG_PASSWORD: kong # Database password
services:
kong-database:
container_name: kong-database
image: postgres:latest # Official Postgres image
restart: on-failure # Restart if the container fails
volumes:
- kong_db_data:/var/lib/postgresql/data # Mount the volume for persistent data
networks:
- kong-net # Connect to the shared Kong network
environment:
POSTGRES_USER: kong # Set DB user inside the container
POSTGRES_DB: kong # Create this database on first run
POSTGRES_PASSWORD: kong # Set the password for the DB user
healthcheck: # Ensure the DB is ready before starting dependent services
test: ["CMD", "pg_isready", "-U", "kong"]
interval: 5s
timeout: 10s
retries: 10
ports:
- '5432:5432' # Optional: expose Postgres on localhost for debugging
kong-bootstrap:
image: '${GW_IMAGE:-kong-eureka:latest}' # Kong Gateway image (default to latest version)
container_name: kong-bootstrap
networks:
- kong-net
depends_on:
kong-database:
condition: service_healthy # Wait until Postgres is up and healthy
restart: on-failure
environment:
<<: *kong-env # Reuse environment config from x-kong-config
KONG_PASSWORD: handyshake # Admin GUI password (required for RBAC)
command: kong migrations bootstrap # Run DB migrations to initialize Kong schema
kong-cp:
image: '${GW_IMAGE:-kong-eureka:latest}' # Main Kong Gateway Control Plane (default to latest version)
container_name: kong-cp
restart: on-failure
networks:
- kong-net
environment:
<<: *kong-env
KONG_ADMIN_LISTEN: 0.0.0.0:8001, 0.0.0.0:8444 ssl # Admin API on HTTP + HTTPS
KONG_ADMIN_GUI_LISTEN: 0.0.0.0:8002, 0.0.0.0:8445 ssl # Kong Manager on HTTP + HTTPS
KONG_ADMIN_GUI_URL: http://${GW_HOST:-localhost}:8002 # URL for GUI links
KONG_PASSWORD: handyshake # Required for logging in to Kong Manager (RBAC)
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_PLUGINS: bundled
depends_on:
kong-bootstrap:
condition: service_completed_successfully # Start only after bootstrap has succeeded
ports:
- "8000:8000" # Proxy HTTP
- "8443:8443" # Proxy HTTPS
- "8001:8001" # Admin API HTTP
- "8444:8444" # Admin API HTTPS
- "8002:8002" # Kong Manager HTTP
- "8445:8445" # Kong Manager HTTPS
wiremock:
image: wiremock/wiremock:latest # or a specific version like 2.35.0
container_name: wiremock-server
networks:
- kong-net
ports:
- "8080:8080" # WireMock HTTP server
volumes:
- ./wiremock-data:/home/wiremock # Mount a volume for mappings and files
command: --verbose # Optional: add WireMock startup parameters
This docker-compose.yml file defines a multi-service application and based on docker-compose file from Install Kong Gateway using Docker Compose section of official Kong documentation:
kong-database: A PostgreSQL database container that Kong uses to store its configuration. It uses a named volume (kong_db_data) for data persistence.
kong-bootstrap: A temporary service that runs Kong database migrations to set up the schema in PostgreSQL.
kong-cp: The main Kong Control Plane service, which runs the Kong Gateway. It exposes various ports for the proxy (8000/8443), Admin API (8001/8444), and Kong Manager GUI (8002/8445). It waits for the kong-bootstrap to complete successfully. It defaults to using the kong-eureka:latest image.
wiremock: A WireMock server, useful for API mocking during development or testing. It's connected to the same network as Kong and exposes port 8080. It also mounts a volume for persisting mappings.
kong-net: A custom bridge network for internal communication between services.
kong_db_data: A named volume for persistent PostgreSQL data.
1.2 Prepare for WireMock Create a directory for its persistent data and mappings:
mkdir wiremock-data
and two sub-directories
__files – place in this directory
mappings – place in this directory
1.3 Start the services with Docker Compose: Ensure you are in the directory containing docker-compose.yml.
# To use your custom 'kong-eureka' image (which is the default in the provided docker-compose.yml)
docker compose up -d
# If you want to explicitly specify the image (e.g., if you renamed it or want to use a specific tag)
# GW_IMAGE=kong-eureka:latest docker compose up -d
2. Verify the installation
Verify Kong Gateway Admin API
curl -X GET "http://localhost:8001/"
You should receive a JSON response from Kong's Admin API:
