Skip to main content
Version: 0.8.x

⚡️ Quick Start

Welcome to the lunar.dev quickstart guide! This tutorial is designed to cover the basic steps of installing the two key components - Lunar Proxy and Lunar Interceptor - that allow lunar.dev to do its magic. Then we'll create a basic policy that shows how easy it is to control and optimize your API consumption.

Below, you'll find a helpful video introduction followed by detailed setup instructions for Docker or Kubernetes, and programming language-specific installations. Let's dive in.

Integrate Lunar.dev into your application in two minutes.
Prerequisites

To facilitate a smooth setup, ensure you meet the following prerequisites:

  • Environment Setup: Choose either Docker or Kubernetes for your environment. Having one of these installed is essential for deploying Lunar Proxy.

  • Development Environment: Ensure you have at least one of the following programming environments installed on your system: Python, Node.js, or Java. This is required for installing Lunar Interceptor and integrating it into your application.

Lunar Proxy Installation​

Step 1: Run Lunar's Proxy Container​

docker run -d --rm -p 8000:8000 -p 8081:8081 -p 8040:8040 -e TENANT_NAME="ORGANIZATION" -v $(pwd):/etc/lunar-proxy --name lunar-proxy lunarapi/lunar-proxy:latest
caution

Note that the TENANT_NAME environment variable is required. This variable should be set to the name of your organization.

Step 2: Run Post-Installation Health-Check​

curl http://localhost:8040/healthcheck

A correct result should be proxy is up.

Step 3: Pass an API Request​

curl http://localhost:8000/fact -H "Host: catfact.ninja" -H "X-Lunar-Scheme: https"

Then, use the discover command to validate that the requests were passed through Lunar Proxy.

docker exec lunar-proxy discover

Lunar Interceptor Installation​

tip

Lunar Interceptor needs to be imported to your app. In case you don't have a relevant app in place, refer to our Example Apps

Step 1: Install Lunar Interceptor​

pip3 install --upgrade lunar-interceptor
export LUNAR_PROXY_HOST="localhost:8000"
note

This environment variable sets the host and port for Lunar Proxy. Set this to localhost:8000 if you're running Lunar Proxy in a local Docker container. The value assigned to LUNAR_PROXY_HOST should only include the hostname and port, without the HTTP prefix. For example, use localhost:8000 and not http://localhost:8000.

Step 3: Import Lunar Interceptor to Your App​

import lunar_interceptor
# imports ...

# your code
def main():

Step 4: Run Your App and Validate Proxy/Interceptor Linkage​

Run your app and consume API traffic. Then, use the discover command to validate that the requests were passed through Lunar Proxy, and that your installed interceptor is correctly listed.

docker exec lunar-proxy discover

Configuration​

Configure the policies.yaml file​

After confirming successful installations of Lunar Interceptor and Lunar Proxy, enhance your API consumption with a remedy plugin. Think of it as a customizable tool that simplifies problem-solving and smoothens API interactions by establishing rules for different scenarios.

In this example, we'll apply the strategy-based-throttling plugin. Edit your policies.yaml file from step two with the provided plugin configuration.

/etc/lunar-proxy/policies.yaml
global:
    remedies:
      - name: Strategy Based Throttling Quick Start
        enabled: true
        config:
          strategy_based_throttling:
            allowed_request_count: 100
            window_size_in_seconds: 60
            response_status_code: 429

In the above example, the plugin will enforce a limit of 100 requests per minute for all requests. If the limit is exceeded, the plugin will return a 429 HTTP status code.

Apply Policy​

After making changes to your local policies.yaml file, use the apply_policies command to apply the new policies.

docker exec lunar-proxy apply_policies