Introduction

kaja is a code-based UI for exploring and calling Twirp APIs. Support for gRPC is coming later.

You can embedded kaja into your development workflow as a Docker container. Desktop version is coming later.

docker run --pull always --name kaja -d -p 41520:41520 \
    -v /my_app/proto:/workspace/proto -e BASE_URL="http://host.docker.internal:8080" \
    --add-host=host.docker.internal:host-gateway kajatools/kaja:latest

docker run arguments explained:

• --pull always - Always pull the latest image from Docker Hub. kaja is updated frequently.
• --name kaja - Name the container. Useful for managing multiple containers.
• -d - Run the container in the detached mode.
• -p 41520:41520 - Expose the container's port 41520 on the host's port 41520. kaja listens on port 41520 by default.
• -v /my_app/proto:/workspace/proto - Mount the /my_app/proto directory from the host file system into the container's /workspace/proto directory. kaja will recursively search for .proto files in this directory. /my_app/proto should be your application's --proto_path, the directory where your .proto files are located.
• -e BASE_URL="http://host.docker.internal:8080" - Set the BASE_URL environment variable. This is the base URL of the Twirp API. kaja will use this URL to when calling the Twirp APIs. See Configuration for all the available configuration options.
• --add-host=host.docker.internal:host-gateway - Expose the host's locahost to the container. This is required for kaja to be able to call the Twirp API from inside the container.
• kajatools/kaja:latest - kaja is available on Docker Hub.

Configuration

Configuration can be provided via environment variables or a config file. Use the -e parameter when running the Docker container.

docker run -e BASE_URL="http://host.docker.internal:8080" ...

List of configuration options:

• BASE_URL - The base URL of the Twirp API. Example: http://host.docker.internal:8080.
• HEADER_1 - Custom HTTP header that will be passed with each Twirp request. Typically used for authentication. Example: Authentication: Bearer <token>.
• HEADER_2 - Another custom HTTP header.
• HEADER_{3..5} - More custom HTTP headers. Up to five in total.

Alternatively, kaja will use dotenv to look for a .env file in the /app directory of the Docker container. You can use the -v parameter to mount a .env file from the host file system. This is useful when you need to dynamically change the configuration. For example, when an authentication header needs to refreshed.

docker run -v /tmp/kaja.env:/app/.env ...

Development

Run: scripts/run Test: (cd ui && npm test)