Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:
The playground requires approximately 4GB of RAM and 10GB of disk space to run all services.

​
Installation

1

Clone the repository

git clone https://github.com/krakend/playground-community.git
cd playground-community
2

Start all services

make start
This command will:
  • Build the web client container
  • Pull all required Docker images
  • Start the entire stack (KrakenD, observability, auth, backends)
The first startup may take 2-3 minutes as Docker downloads all images.
3

Wait for services to be ready

Monitor the startup process:
make logs
Look for messages indicating services are ready, such as:
  • KrakenD: Starting HTTP server
  • Keycloak: Admin console listening
  • Grafana: HTTP Server Listen

​
Access the Services

Once all services are running, you can access them at the following URLs:
ServiceURLCredentials
KrakenD API Gatewayhttp://localhost:8080-
Fake API Backendhttp://localhost:8000-
Grafana (Metrics)http://localhost:4000admin / admin
Jaeger (Tracing)http://localhost:16686-
Kibana (Logs)http://localhost:5601-
Web Client SPAhttp://localhost:3000-
JWT Revokerhttp://localhost:9000-
Keycloak (IdP)http://localhost:8085admin / admin
RabbitMQ Managementhttp://localhost:15672guest / guest

​
Your First API Call

Test the gateway with a simple request: 
curl http://localhost:8080/public
You should receive a JSON response from the backend service.

​
Try More Examples

​
GitHub User Aggregation

Fetch and aggregate GitHub user data: 
curl http://localhost:8080/git/krakend
This endpoint:
  • Calls GitHub API to get user profile
  • Calls GitHub API to get user repositories
  • Aggregates the data into a single response
  • Filters and maps fields

​
GraphQL to REST

Transform a GraphQL query into a REST endpoint: 
curl http://localhost:8080/starwars_films/1
This converts a GraphQL query to the Star Wars API into a simple REST endpoint.

​
JWT-Protected Endpoint

Try accessing a protected endpoint: 
# Without token - returns 401 Unauthorized
curl http://localhost:8080/private/moderate

# Get token from Keycloak and retry with authentication
Visit http://localhost:3000 to use the web client that handles authentication automatically.

​
Keycloak Users

The playground includes pre-configured test users:
UsernamePasswordRoles
moderatormoderatormoderator
readerreaderreader
Use these credentials at http://localhost:3000 or to obtain JWT tokens from Keycloak.

​
View Observability Data

​
Grafana (Metrics)

  1. Open http://localhost:4000
  2. Login with admin / admin
  3. Navigate to Dashboards → KrakenD
You’ll see real-time metrics including:
  • Request rate
  • Response times
  • Error rates
  • Backend health

​
Jaeger (Tracing)

  1. Open http://localhost:16686
  2. Select krakend from the Service dropdown
  3. Click Find Traces
View distributed traces showing request flow through the gateway and backends.

​
Kibana (Logs)

  1. Open http://localhost:5601
  2. Import the pre-configured dashboard:
make elastic
This imports log visualizations showing KrakenD activity.

​
Managing the Playground

​
View Logs

Follow logs from all services: 
make logs
Or view logs for a specific service: 
docker compose logs -f krakend_ce

​
Restart Services

Restart all services: 
make restart
Or restart a specific service: 
docker compose restart krakend_ce

​
Stop the Playground

Stop all services and remove volumes: 
make stop
This completely cleans up the environment.

​
Configuration Changes

The KrakenD configuration is located at config/krakend/krakend.json. When you modify this file, KrakenD automatically reloads the configuration thanks to the :watch image.
Use the KrakenD Designer to visually edit krakend.json. Simply drag the file into the designer, make changes, and download the updated configuration.

​
Next Steps

Explore the Architecture

Understand how all services work together

Learn About Features

Explore API Gateway patterns and examples

Configure Endpoints

Customize KrakenD endpoint configuration

API Reference

Browse all available gateway endpoints
This playground is designed for learning and experimentation only. Do not use it in production environments.

Build docs developers (and LLMs) love

Get started for freeTalk to us