Gateway Stack Guide

The active Swarm layout classifies Kong as an OSS service and Konga as an independently scalable administration panel. The retained Compose layout below keeps them together for rollback and local development.

Source Of TruthCopy Anchor Link

• Active Kong service: swarm/stacks/services/kong/{kong,kong-migrations}.yml (service-kong)

• Active Konga panel: swarm/stacks/panels/konga.yml (panel)

• Active Kong launcher: swarm/scripts/services/kong.{sh,bat}

• Compose: runtime/stacks/infrastructure/gateway/docker-compose.kong.yml

• Bootstrap script: runtime/stacks/infrastructure/gateway/kong-bootstrap-ocelot.sh

• Declarative state: runtime/stacks/infrastructure/gateway/kong.yml

• Mapping reference: runtime/stacks/infrastructure/gateway/ocelot-to-kong-mapping.md

• VPS env: runtime/environments/vps/infrastructure/gateway/.env

• VPS placeholder: runtime/environments/vps/infrastructure/gateway/kong.env

• Dev template: runtime/environments/dev/infrastructure/gateway/kong.dev.env

• Launcher: runtime/scripts/infrastructure/gateway.{sh,bat}

DependenciesCopy Anchor Link

• PostgreSQL stack is up and healthy.
• postgres-network exists.
• kong_db and kong_user exist in PostgreSQL.
• proxy exists.

DeployCopy Anchor Link

./runtime/scripts/infrastructure/gateway.sh up

Raw compose command:

docker compose --env-file runtime/environments/vps/infrastructure/gateway/.env -f runtime/stacks/infrastructure/gateway/docker-compose.kong.yml up -d

First-Time KongaCopy Anchor Link

1. Open https://konga.perspective-v.com from a NetBird-connected client.
2. Create the initial Konga admin user.
3. Add the Kong connection http://kong:8001.

Bootstrap Ocelot ParityCopy Anchor Link

cd runtime/stacks/infrastructure/gateway
set -a
source ../../../environments/vps/infrastructure/gateway/.env
set +a
./kong-bootstrap-ocelot.sh

decK Validation Or SyncCopy Anchor Link

cd runtime/stacks/infrastructure/gateway
set -a
source ../../../environments/vps/infrastructure/gateway/.env
set +a

envsubst < kong.yml > /tmp/kong.rendered.yml
deck file validate /tmp/kong.rendered.yml

KONG_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}} {{end}}' kong | awk '{print $1}')
deck gateway diff --kong-addr "http://$KONG_IP:8001" /tmp/kong.rendered.yml

ValidateCopy Anchor Link

./runtime/scripts/infrastructure/gateway.sh ps
curl -Ik https://api.perspective-v.com
curl -Ik https://konga.perspective-v.com
curl -Ik https://api.perspective-v.com/identity/swagger/v1/swagger.json
curl -Ik https://api.perspective-v.com/graph/docs/

Routing Rules To PreserveCopy Anchor Link

• identity and graph stay as Kong upstream backends.
• console stays a direct Traefik route.
• Public compatibility paths must keep working.
• JWT stays only on protected routes.
• CORS must keep AppCode, Apollo headers, and the approved browser origins.