configcat-proxy

README

ConfigCat Proxy [Beta]

[!NOTE]
The ConfigCat Proxy is in a public beta phase. If you have feedback or questions, please file a GitHub Issue or contact us.

The ConfigCat Proxy allows you to host a feature flag evaluation service in your own infrastructure. It's a small Go application that communicates with ConfigCat's CDN network and caches/proxies config JSON files for your frontend and backend applications. The config JSON contains all the data that is needed for ConfigCat SDKs to evaluate feature flags.

The ConfigCat Proxy provides the following:

• Performance: The Proxy can be deployed close to your applications and can serve the downloaded config JSON files from memory. ConfigCat SDKs then can operate on the proxied config JSON. This can reduce the duration of feature flag evaluation for stateless or short-lived applications.
• Reliability: The Proxy can store the downloaded config JSON files in an external cache. It can fall back to operating on the cached config JSON if the ConfigCat CDN network becomes inaccessible.
• Security: The Proxy can act as a server side flag evaluation component. Using it like that can prevent the exposure of config JSON files to frontend and mobile applications.
• Scalability: Horizontal scaling allows you to align with the load coming from your applications accordingly.
• Streaming: The Proxy provides real-time feature flag change notifications via Server-Sent Events (SSE) and gRPC.

To learn more, read the documentation.

How It Works

The Proxy wraps one or more SDK instances for handling feature flag evaluation requests. It also serves the related config JSON files that can be consumed by other ConfigCat SDKs running in your applications.

Within the Proxy, the underlying SDK instances can run in the following modes:

• Online: In this mode, the underlying SDK has an active connection to the ConfigCat CDN network through the internet.
• Offline: In this mode, the underlying SDK doesn't have an active connection to ConfigCat. Instead, it uses the configured cache or a file as a source of its config JSON.

Communication

There are three ways how the Proxy is informed about the availability of new feature flag evaluation data:

• Polling: The ConfigCat SDKs within the Proxy are regularly polling the ConfigCat CDN for new config JSON versions.
• Webhook: The Proxy has webhook endpoints (for each underlying SDK), which can be set on the ConfigCat Dashboard to be invoked when someone saves & publishes new feature flag changes.
• Cache polling / file watching: In offline mode, the Proxy can regularly poll a cache or watch a file for new config JSON versions.

These are the ports used by the Proxy by default:

• 8050: for standard HTTP communication. (API, CDN proxy, Webhook, SSE, Status)
• 8051: for providing prometheus metrics.
• 50051: for gRPC communication.

Installation

You can install the ConfigCat Proxy from the following sources:

Docker

The docker image is available on DockerHub. You can run the image either as a standalone docker container or via docker-compose.

1. Pull the latest image:

   docker pull configcat/proxy:latest
   

2. Run the ConfigCat Proxy:

   docker run -d --name configcat-proxy \ 
     -p 8050:8050 -p 8051:8051 -p 50051:50051 \
     -e CONFIGCAT_SDKS='{"<sdk-identifier>":"<your-sdk-key>"}' \
     configcat/proxy
   

Using with docker-compose:

1. Put the following into your docker-compose.yml:

   services:
     configcat_proxy:
       image: configcat/proxy:latest
       environment:
         - CONFIGCAT_SDKS={"<sdk-identifier>":"<your-sdk-key>"}
       ports:
         - "8050:8050"
         - "8051:8051"
         - "50051:50051"
   

2. Start docker services by executing the following command:

   docker-compose up -f docker-compose.yml -d
   

Standalone Executables

You can download the executables directly from GitHub Releases for your desired platform.

Health Check

After installation, you can check the status endpoint of the Proxy to ensure it's working correctly: http(s)://localhost:8050/status

Need help?

https://configcat.com/support

Contributing

Contributions are welcome. Please read the Contribution Guideline for more info.

About ConfigCat

ConfigCat is a feature flag, feature toggle, and configuration management service that lets you launch new features and change your software configuration remotely without actually (re)deploying code. ConfigCat even helps you do controlled roll-outs like canary releases and blue-green deployments.

ConfigCat is a hosted feature flag service. Manage feature toggles across frontend, backend, mobile, and desktop apps. Alternative to LaunchDarkly. Management app + feature flag SDKs.

• Documentation
• Blog