{"id":13576691,"url":"https://github.com/TheLunarCompany/lunar","last_synced_at":"2025-04-05T08:32:55.752Z","repository":{"id":193842932,"uuid":"678765416","full_name":"TheLunarCompany/lunar","owner":"TheLunarCompany","description":"lunar.dev: Ground Control for 3rd Party APIs","archived":false,"fork":false,"pushed_at":"2025-04-01T18:11:37.000Z","size":8670,"stargazers_count":123,"open_issues_count":2,"forks_count":6,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-01T18:27:49.173Z","etag":null,"topics":["api","api-consumer","api-consumption","api-proxy","caching","event-management","golang","orchestration","priority-queue","quota","rate-limit","resilience","throttling","visibility"],"latest_commit_sha":null,"homepage":"https://lunar.dev","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TheLunarCompany.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-15T10:22:02.000Z","updated_at":"2025-04-01T18:11:41.000Z","dependencies_parsed_at":"2023-10-23T14:48:18.516Z","dependency_job_id":"bc21262e-dbf0-428e-8ead-f77790995535","html_url":"https://github.com/TheLunarCompany/lunar","commit_stats":null,"previous_names":["thelunarcompany/lunar"],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheLunarCompany%2Flunar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheLunarCompany%2Flunar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheLunarCompany%2Flunar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheLunarCompany%2Flunar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheLunarCompany","download_url":"https://codeload.github.com/TheLunarCompany/lunar/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247311975,"owners_count":20918340,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-consumer","api-consumption","api-proxy","caching","event-management","golang","orchestration","priority-queue","quota","rate-limit","resilience","throttling","visibility"],"created_at":"2024-08-01T15:01:12.946Z","updated_at":"2025-04-05T08:32:55.627Z","avatar_url":"https://github.com/TheLunarCompany.png","language":"Go","funding_links":[],"categories":["Go","📚 Projects (1974 total)","Aggregators","📂 카테고리","MCP Utilities \u0026 Tools","TypeScript"],"sub_categories":["MCP Servers","🔗 Aggregators","Gateways"],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"./readme-files/logo-light.png#gh-light-mode-only\" width=\"50%\" height=\"50%\" /\u003e\n\u003cimg src=\"./readme-files/logo-dark.png#gh-dark-mode-only\" width=\"50%\" height=\"50%\" /\u003e\n\n\u003ca href=\"https://hub.docker.com/r/lunarapi/lunar-proxy\"\u003e![Docker Pulls](https://img.shields.io/docker/pulls/lunarapi/lunar-proxy)\u003c/a\u003e\n\u003ca href=\"https://opensource.org/licenses/MIT\"\u003e![License](https://img.shields.io/badge/License-MIT-blue.svg)\u003c/a\u003e\n\u003ca href=\"https://docs.lunar.dev/\"\u003e![Documentation](https://img.shields.io/badge/docs-viewdocs-blue.svg?style=flat-square \"Viewdocs\")\u003c/a\u003e\n\u003ca href=\"https://lunar.dev/\"\u003e![Website](https://img.shields.io/badge/lunar.dev-website-purple.svg?style=flat-square \"Website\")\u003c/a\u003e\n\nLunar.dev's mission is to enable optimization and control of third-party API consumption in production environments. Lunar is a lightweight tool that empowers Software architects, DevOps and engineering teams to centralize consumption, gain insight and visibility into usage patterns and costs, and utilize out-of-the-box policies.\n\nWe've released a new version dedicated to production environments including advanced management and metric enhancement capabilities for companies. To gain access you will need a guided, hands-on experience to utilize the Lunar.dev platform as offered on our different tiers - via the website or reach out to us at Lunar.dev.\n\nThis project was born out of the need to have a better, and stable solution to managing 3rd party API consumption, and we're proud to keep it open-source at its core. It will remain free for personal use (not in production) Detailed information and documentation on the lunar.dev website.\n\n\u003c/div\u003e\n\n# ⚡️ Quick Start\n\nWelcome to the lunar.dev quickstart guide! This tutorial is designed to cover the basic steps of installing the two key components - Lunar Gatway 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.\n\nBelow, 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.\n\n### Lunar Proxy Installation\n\n### Option 1: Docker\n\n#### Step 1: Run Lunar's Proxy Container\n\n```bash\ndocker 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\n```\n\n:::caution\n**Note that the `TENANT_NAME` environment variable is required. This variable should be set to the name of your organization.**\n:::\n\n#### Step 2: Run Post-Installation Health-Check\n\n```bash\ncurl http://localhost:8040/healthcheck\n```\n\nA correct result should be `proxy is up`.\n\n#### Step 3: Pass an API Request\n\n```bash\ncurl http://localhost:8000/fact -H \"x-lunar-host: catfact.ninja\" -H \"x-lunar-scheme: https\"\n```\n\nThen, use the [Discover](/product-features/discover) command to validate that the requests were passed through Lunar Proxy.\n\n```bash\ndocker exec lunar-proxy discover\n```\n\n### Option 2: Kubernetes\n\n#### Step 1: Add and Update Lunar Repository\n\n```bash\nhelm repo add lunar https://thelunarcompany.github.io/proxy-helm-chart/\nhelm repo update\n```\n\n#### Step 2: Install Lunar Proxy Helm Chart\n\n```bash\nhelm install lunar-proxy lunar/lunar-proxy --set tenantName=\u003cname\u003e --namespace lunar-proxy --create-namespace\n```\n\nBefore installing Lunar's Proxy, ensure that the `tenantName` is set to the name of your organization, for example: `Acme` or `Google`.\n\n#### Step 3: Run Post-Installation Health-Check\n\n```bash\nhelm test lunar-proxy\n```\n\n#### Step 4: Pass an API Request\n\n```bash\ncurl http://localhost:8000/fact -H \"x-lunar-host: catfact.ninja\" -H \"x-lunar-scheme: https\"\n```\n\nThen, use the `discover` command to validate that the requests were passed through Lunar Proxy.\n\n```bash\nkubectl exec \u003clunar-proxy-pod-name\u003e -- discover\n```\n\n### Lunar Interceptor Installation\n\nLunar Interceptor needs to be imported to your app. In case you don't have a relevant app in place, refer to our [Example Apps](https://github.com/TheLunarCompany/lunar/blob/main/example-consumer-app)\n\n### Step 1: Install Lunar Interceptor\n\n#### Python\n\n```bash\npip3 install 'lunar-interceptor==0.4.*'\n```\n\n#### Node.JS\n\n```bash\nnpm install lunar-interceptor\n```\n\n#### Java\n\n```\nwget -O lunarInterceptor.jar https://s01.oss.sonatype.org/content/repositories/releases/dev/lunar/interceptor/lunar-interceptor/0.1.1/lunar-interceptor-0.1.1.jar\n```\n\n### Step 2: Link Lunar Interceptor to Lunar Proxy\n\n```bash\nexport LUNAR_PROXY_HOST=\"lunar-proxy:8000\"\n```\n\nNote: The value assigned to LUNAR_PROXY_HOST should only include the hostname and port, without the HTTP prefix. For example, use \"lunar-proxy:8000\" and not \"http://lunar-proxy:8000\".\n\n### Step 3: Import Lunar Interceptor to Your App\n\n#### Python\n\n```python\nimport lunar_interceptor\n# imports ...\n\n# your code\ndef main():\n```\n\n#### Node.JS\n\n```python\nrequire(\"lunar-interceptor\")\n# imports ...\n\n# your code\n```\n\n#### Java\n\nEnable the instrumentation agent by using the `-javaagent` flag with the JVM.\n\n```bash\nexport JAVA_TOOL_OPTIONS=\"-javaagent:PATH/TO/lunarInterceptor.jar\"\n```\n\n#### Step 4: Run Your App and Validate Proxy/Interceptor Linkage\n\nRun your app and consume API traffic. Then, use the [Discover](product-features/discover) command to validate that the requests were passed through Lunar Proxy, and that your installed interceptor is correctly listed.\n\n### Option 1: Docker\n\n```bash\ndocker exec lunar-proxy discover\n```\n\n### Option 2: Kubernetes\n\n```bash\nkubectl exec \u003clunar-proxy-pod-name\u003e -- discover\n```\n\n### Configuration\n\n### Configure the `flow.yaml` and `quota.yaml` files\n\nAfter confirming successful installation of lunar.dev, enhance your API consumption with a Lunar Flow.Think of it as a customizable tool that simplifies problem-solving and smoothens API interactions by establishing rules for different scenarios.\n\n**/etc/lunar-proxy/flows/flow.yaml**\n\n```yaml\nname: ClientSideLimitingFlow\n\nfilter:\n  url: api.website.com/*\n\nprocessors:\n  Limiter:\n    processor: Limiter\n    parameters:\n      - key: quota_id\n        value: MyQuota\n\n  GenerateResponseLimitExceeded:\n    processor: GenerateResponse\n    parameters:\n      - key: status\n        value: 429\n      - key: body\n        value: \"Quota Exceeded. Please try again later.\"\n      - key: Content-Type\n        value: text/plain\n\nflow:\n  request:\n    - from:\n        stream:\n          name: globalStream\n          at: start\n      to:\n        processor:\n          name: Limiter\n\n    - from:\n        processor:\n          name: Limiter\n          condition: block\n      to:\n        processor:\n          name: GenerateResponseLimitExceeded\n\n    - from:\n        processor:\n          name: Limiter\n          condition: allow\n      to:\n        stream:\n          name: globalStream\n          at: end\n\n  response:\n    - from:\n        processor:\n          name: GenerateResponseLimitExceeded\n      to:\n        stream:\n          name: globalStream\n          at: end\n\n    - from:\n        stream:\n          name: globalStream\n          at: start\n      to:\n        processor:\n          name: end\n```\n\n**/etc/lunar-proxy/quotas/quota.yaml**\n\n```yaml\nquotas:\n  - id: MyQuota\n    filter:\n      url: api.website.com/*\n    strategy:\n      fixed_window:\n        max: 100\n        interval: 1\n        interval_unit: minute\n```\n\nIn the above example, the plugin will enforce a limit of 100 requests per minute the [`api.website.com/*`](http://api.website.com/*) API endpoint. If the limit is exceeded, the plugin will return a Lunar-generated API response with 429 HTTP status code.\n\n#### Load Flows\n\nAfter you have altered `flow.yaml` and `quota.yaml` according to your needs, run the `load_flows` command:\n\n```docker\ndocker exec lunar-proxy load_flows\n```\n\n### Demo\n\nCheck out our demo video for a quick start [here](https://youtu.be/ObJDfbSB5N8).\n\n### Lunar Sandbox\n\nTo try out Lunar without installing anything, check out our [sandbox](https://docs.lunar.dev/additional-resources/lunar-sandbox).\n\n## Getting Help\n\nFor any questions, feel free to reach out to us at [info@lunar.dev](mailto:info@lunar.dev).\n\n## Testing / Linting\n\n### Proxy\n\nTo run tests:\n\n```\ncd proxy/integration-tests\npipenv install --dev\npipenv run behave\n```\n\nLinting is described [here](https://github.com/TheLunarCompany/lunar/blob/main/readme-files/LINTING.md).\n\n### Interceptor\n\nTo run tests:\n\n```\ncd interceptors/integration-tests\npipenv install --dev\n\nexport CLIENT_LANGUAGE=python CLIENT_VERSION=3.10  # For Python tests\n# OR\nexport CLIENT_LANGUAGE=java                        # For Java tests\n\npipenv run behave\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTheLunarCompany%2Flunar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTheLunarCompany%2Flunar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTheLunarCompany%2Flunar/lists"}