DPTCloud
Back to articles
Technology Insight

Self-Hosting an API Management and Distribution Platform: Integrating Kong Gateway and Keycloak on VPS Ubuntu 26.04

June 3, 2026

Introduction: The Imperative of Self-Hosted API Governance

In the modern enterprise ecosystem, APIs (Application Programming Interfaces) serve as the fundamental nervous system connecting disparate microservices, legacy databases, and frontend applications. However, as an organization scales its digital infrastructure, managing these endpoints securely becomes a monumental challenge. Relying entirely on proprietary, cloud-managed API gateways can lead to vendor lock-in, unpredictable data egress costs, and potential compliance bottlenecks regarding data residency.

Self-hosting your API management layer offers an elegant alternative. By combining Kong Gateway, the world's most popular open-source cloud-native API gateway, with Keycloak, a robust open-source Identity and Access Management (IAM) solution, businesses can establish a high-performance, secure, and fully customized API distribution platform. Deploying this architecture on a reliable Virtual Private Server (VPS) running the cutting-edge Ubuntu 26.04 LTS ensures long-term stability, modern kernel optimizations, and strict security compliance. This guide delivers an enterprise-grade blueprint for engineering this exact ecosystem from scratch.

---

Architecture Overview: How Kong and Keycloak Intersect

Before executing technical commands, it is crucial to understand the structural topology of the platform we are constructing. The architecture relies on a clear separation of concerns:

  • The Client: Consumes the API endpoints via external applications, mobile apps, or third-party integrations.
  • Kong Gateway: Acts as the single entry point (Reverse Proxy). It intercepts all incoming HTTP/HTTPS traffic, handles rate limiting, routes requests to upstream microservices, and offloads authentication.
  • Keycloak: Serves as the centralized Identity Provider (IdP). It manages user directories, client credentials, and issues cryptographically secure JSON Web Tokens (JWTs) via the OpenID Connect (OIDC) protocol.
  • Upstream Services: Your backend business logic/microservices, shielded safely behind the private network layer of the VPS, completely inaccessible to the public internet except through Kong.
When a client requests a protected resource, Kong intercepts the request, verifies the bearer token against Keycloak's public keys, enforces defined rate limits, and safely forwards authorized requests to the backend service. This drastically reduces the security overhead required within your actual application code.
---

Prerequisites and Environment Initialization

To follow this deployment guide seamlessly, ensure your environment meets the following baseline requirements:

  1. A dedicated VPS running Ubuntu 26.04 LTS with a minimum of 2 vCPUs and 4GB of RAM (Keycloak's Java runtime requires adequate memory allocations).
  2. A fully qualified domain name (FQDN) with DNS records pointing to your VPS IP address (e.g., api.yourcompany.com and auth.yourcompany.com).
  3. Root or sudo administrative privileges on the target server.

Step 1: System Modernization and Core Dependencies

Log in to your Ubuntu 26.04 instance via SSH and execute a comprehensive system update to patch the core kernel and native repository definitions:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget apt-transport-https gnupg2 software-properties-common ufw

Configure the Uncomplicated Firewall (UFW) to permit standard SSH, HTTP, and HTTPS traffic while locking down database ports:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
---

Step 2: Deploying a Resilient Database Layer (PostgreSQL)

Both Kong Gateway (in database mode) and Keycloak require a highly reliable relational database backend. We will deploy a unified PostgreSQL cluster, establishing separate logical databases and distinct database users for each application to enforce security isolation.

Installing PostgreSQL 17+ on Ubuntu 26.04

sudo apt install -y postgresql postgresql-contrib
sudo systemctl enable postgresql
sudo systemctl start postgresql

Database Provisioning for Kong and Keycloak

Access the PostgreSQL prompt as the administrative user and execute the following structural setup:

sudo -i -u postgres psql

-- Create Database and User for Kong
CREATE USER kong WITH PASSWORD 'YourSecureKongPassword';
CREATE DATABASE kong OWNER kong;
GRANT ALL PRIVILEGES ON DATABASE kong TO kong;

-- Create Database and User for Keycloak
CREATE USER keycloak WITH PASSWORD 'YourSecureKeycloakPassword';
CREATE DATABASE keycloak OWNER keycloak;
GRANT ALL PRIVILEGES ON DATABASE keycloak TO keycloak;

\q
---

Step 3: Installing and Configuring Kong Gateway

With the database prepared, we proceed to install the official Kong Gateway open-source package onto the Ubuntu 26.04 filesystem.

Adding the Official Kong Repository

curl -1sLf '[https://packages.konghq.com/public/gateway/cfg/setup/bash.deb.sh&apos](https://packages.konghq.com/public/gateway/cfg/setup/bash.deb.sh&apos); | sudo bash
sudo apt update
sudo apt install -y kong

Configuring the Environment File

Copy the default configuration template and adjust the parameters to connect to your PostgreSQL database instance:

sudo cp /etc/kong/kong.conf.default /etc/kong/kong.conf
sudo nano /etc/kong/kong.conf

Modify or append the following core variables within /etc/kong/kong.conf:

database = postgres
pg_host = 127.0.0.1
pg_user = kong
pg_password = YourSecureKongPassword
pg_database = kong
proxy_listen = 0.0.0.0:8000, 0.0.0.0:8443 ssl
admin_listen = 127.0.0.1:8001

Running Database Migrations and Starting Kong

Bootstrap the PostgreSQL database schema using Kong's native migration utility:

sudo kong migrations bootstrap -c /etc/kong/kong.conf
sudo systemctl start kong
sudo systemctl enable kong

Verify the health of the gateway by hitting the internal admin API loopback: curl [http://127.0.0.1:8001/](http://127.0.0.1:8001/).

---

Step 4: Setting Up Keycloak with Systemd Integration

Keycloak requires a Java Runtime Environment (JRE). We will install OpenJDK and configure Keycloak as a structured background system service.

Installing Java and Extracting Keycloak

sudo apt install -y openjdk-21-jdk
wget [https://github.com/keycloak/keycloak/releases/download/24.0.5/keycloak-24.0.5.tar.gz](https://github.com/keycloak/keycloak/releases/download/24.0.5/keycloak-24.0.5.tar.gz)
sudo tar -xvzf keycloak-24.0.5.tar.gz -C /opt/
sudo mv /opt/keycloak-24.0.5 /opt/keycloak

Configuring Keycloak Production Environment

Edit the /opt/keycloak/conf/keycloak.conf production properties file:

db=postgres
db-username=keycloak
db-password=YourSecureKeycloakPassword
db-url=jdbc:postgresql://localhost:5432/keycloak
http-enabled=true
http-port=8080
proxy=edge

Building a Systemd Service for Keycloak

To ensure automated service recovery on server reboots, create a systemd configuration definition:

sudo nano /etc/systemd/system/keycloak.service

Insert the following service manifest:

[Unit]
Description=Keycloak Identity Provider
After=network.target postgresql.service

[Service]
Type=simple
User=root
Env=KEYCLOAK_ADMIN=admin
Env=KEYCLOAK_ADMIN_PASSWORD=YourUltraSecureAdminPassword
ExecStart=/opt/keycloak/bin/kc.sh start
Restart=always

[Install]
WantedBy=multi-user.target

Reload the system daemon, start the server process, and check status parameters:

sudo systemctl daemon-reload
sudo systemctl start keycloak
sudo systemctl enable keycloak
---

Step 5: Securing Traffic via Nginx Reverse Proxy and Let's Encrypt

To securely expose Kong's APIs and Keycloak's UI to the public internet, we deploy Nginx as a reverse proxy coupled with Let's Encrypt SSL certificates.

sudo apt install -y nginx certbot python3-certbot-nginx

Provisioning SSL Certificates

sudo certbot certonly --nginx -d api.yourcompany.com
sudo certbot certonly --nginx -d auth.yourcompany.com

Configuring Nginx Blocks

Create a dedicated server definition at /etc/nginx/sites-available/api-gateway:

server {
    listen 443 ssl http2;
    server_name auth.yourcompany.com;

    ssl_certificate /etc/letsencrypt/live/[auth.yourcompany.com/fullchain.pem](https://auth.yourcompany.com/fullchain.pem);
    ssl_certificate_key /etc/letsencrypt/live/[auth.yourcompany.com/privkey.pem](https://auth.yourcompany.com/privkey.pem);

    location / {
        proxy_pass [http://127.0.0.1:8080](http://127.0.0.1:8080);
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
}

Link the site configuration and restart Nginx to apply your production configurations: sudo ln -s /etc/nginx/sites-available/api-gateway /etc/nginx/sites-enabled/ && sudo systemctl restart nginx.

---

Step 6: Integrating Kong and Keycloak via OpenID Connect (OIDC)

With both platforms exposed securely under valid SSL configurations, the final stage is binding them together. Within the Keycloak Admin Console (auth.yourcompany.com):

  1. Create a new Realm designated for your API consumers (e.g., Enterprise-API).
  2. Create a new Client named kong-gateway with the Access Type set to confidential.
  3. Configure the Valid Redirect URIs to point toward your API domain path: [https://api.yourcompany.com/](https://api.yourcompany.com/)*.
  4. Navigate to the Credentials tab and safely extract the generated Client Secret value.

Applying the OIDC Plugin to Kong Routes

Using Kong's Admin API, you can seamlessly protect any exposed upstream route. Execute an HTTP POST to activate the open-source JWT verification plugin or an OIDC plugin mapping back to Keycloak's public keys:

curl -X POST [http://127.0.0.1:8001/routes/YOUR_ROUTE_ID/plugins](http://127.0.0.1:8001/routes/YOUR_ROUTE_ID/plugins) \
  --data "name=jwt" \
  --data "config.claims_to_verify=exp"

By default, Kong will look for an Authorization: Bearer header inside incoming client requests. It verifies the signature against the OpenID Connect discovery endpoint hosted by your Keycloak cluster ([https://auth.yourcompany.com/realms/Enterprise-API/.well-known/openid-configuration](https://auth.yourcompany.com/realms/Enterprise-API/.well-known/openid-configuration)). If valid, access is granted instantly.

---

Conclusion: Maintenance, Security, and Scalability

You have successfully engineered a self-hosted, enterprise-ready API Management and Distribution platform using Kong Gateway and Keycloak on a modern Ubuntu 26.04 LTS VPS instance. This layout cuts cloud subscription costs while granting your DevOps engineering teams full sovereignty over authorization rules, rate limiting parameters, and API performance telemetry.

As your API traffic metrics compound over time, you can horizontally scale this architecture easily by splitting PostgreSQL out onto a dedicated managed cluster and spinning up multiple stateless Kong VPS instances behind a global round-robin load balancer.

Self-Hosting an API Management and Distribution Platform: Integrating Kong Gateway and Keycloak on VPS Ubuntu 26.04 | DPTCloud