{"id":21898261,"url":"https://github.com/fasibio/graphqldockerproxy","last_synced_at":"2025-04-15T18:32:51.579Z","repository":{"id":38810297,"uuid":"134247993","full_name":"fasibio/GraphqlDockerProxy","owner":"fasibio","description":"A generic Graphql API for Docker and Kubernetes","archived":false,"fork":false,"pushed_at":"2022-12-08T17:16:18.000Z","size":8515,"stargazers_count":36,"open_issues_count":28,"forks_count":4,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-28T23:34:44.377Z","etag":null,"topics":["api-gateway","docker","docker-image","graphql","graphql-server","kubernetes","proxy"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fasibio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-21T09:30:34.000Z","updated_at":"2024-02-11T23:05:57.000Z","dependencies_parsed_at":"2023-01-25T15:00:56.732Z","dependency_job_id":null,"html_url":"https://github.com/fasibio/GraphqlDockerProxy","commit_stats":null,"previous_names":[],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fasibio%2FGraphqlDockerProxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fasibio%2FGraphqlDockerProxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fasibio%2FGraphqlDockerProxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fasibio%2FGraphqlDockerProxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fasibio","download_url":"https://codeload.github.com/fasibio/GraphqlDockerProxy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249129226,"owners_count":21217308,"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-gateway","docker","docker-image","graphql","graphql-server","kubernetes","proxy"],"created_at":"2024-11-28T14:25:12.746Z","updated_at":"2025-04-15T18:32:51.563Z","avatar_url":"https://github.com/fasibio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Logo](/doc/assets/logo.png)\n# GraphqlDockerProxy\n\nIt's a generic Graphql Proxy Api Gateway.\n\nTo build Graphql microservices and combine this automatically, in one API, without extra Code.\n\n\n[![Docker Build Status](https://img.shields.io/docker/build/fasibio/graphqldockerproxy.svg)](https://hub.docker.com/r/fasibio/graphqldockerproxy/) \n[![pipeline status](https://gitlab.com/fasibio/GraphqlDockerProxy/badges/master/pipeline.svg)](https://gitlab.com/fasibio/GraphqlDockerProxy/commits/master)\n[![coverage report](https://gitlab.com/fasibio/GraphqlDockerProxy/badges/master/coverage.svg)](https://fasibio.gitlab.io/GraphqlDockerProxy)\n\n![oh man get image not visible](/doc/assets/kontext.png?raw=true)\n\n# Features\n - Continuously integrates the Backend GraphQL Nodes (**No restart!**)\n - !!!It works with **Docker** and **Kubernetes**!!!\n - Supports load balancing (with docker)\n\n\n# Run with Docker (5 Minutes Quickstart)\u003ca name=\"runWithDocker\"\u003e\u003c/a\u003e\n\n### Note\nYou can find examples docker-compose files in the example directory of this git project ([./example/quickstart](/example/quickstart)).\n\n## How Does it Work: \n- It works without dependencies. \n- You can start it in your docker cloud. \n - Use it to manage your GraphQL-Microservices. With docker labels you can registry your microservices in the proxy.\n- The proxy automatically will find your services and add them to the gateway.\n\n## How to Start the Proxy\nIn this example we will use docker-compose to start the proxy. \nHere is an example docker-compose file: \n```\nversion: '3'\nservices: \n  api: \n    restart: always\n    image: fasibio/graphqldockerproxy\n    expose:\n      - 3000\n    ports:\n      - 3000:3000\n    networks:\n     - web\n    environment: \n      - qglProxyRuntime=dockerWatch\n      - dockerNetwork=web\n      - gqlProxyToken=1234\n    volumes: \n     - /var/run/docker.sock:/var/run/docker.sock\nnetworks:\n  web:\n    external: true\n```\nThis will start the proxy on port 3000. \nIt's important to include the ```docker.sock``` as volume.\n\n **That's all!!**\n\n Now you can open the proxy playground under http://127.0.0.1:3000/graphql .\n The API is reachable under http://127.0.0.1:3000/graphql too.\n\n At the moment it is an empty gateway. \n\n ## Let's Start a GraphQL Microservice \n\n\n  For this example we will use the Docker image ```bfillmer/graphql-swapi```\n\n  Create a docker-compose file: \n  ```\n  version: '3'\n  services: \n    swapi: \n      image: bfillmer/graphql-swapi\n      expose:\n        - 9000\n      networks: \n        - web\n      labels: \n        - gqlProxy.token=1234\n        - gqlProxy.url=:9000/graphql\n        - gqlProxy.namespace=swapi\nnetworks:\n    web:\n      external: true\n  ```\n\nStart the docker-compose file. \nThe proxy will automatically find the microservice and include it.\nUnder http://127.0.0.1:3000/graphql you can now see that swapi has wrapped your graphql microservice.\n\nInside this namespace you can make graphql requests. \nFor example:\n```\n{\n  swapi{\n    allFilms{\n      films{\n        title\n      }\n    }\n  }\n}\n```\n\nOr you can use the admin Page to see what has been included http://127.0.0.1:3000/admin/graphql (See the second tab at playground)\n\n\n It is important to put your microservice in the same network as the proxy (In this example the network is called 'web'). \n We have to set the following labels, so that the Api can find the service: \n  - ```gqlProxy.token```: The same token you set in the proxy. (In this example 1234)\n  - ```gqlProxy.url```: This is the relative path to the proxy running inside the container. (For example: :9000/graphql)\n  - ```gqlProxy.namespace```: The namespace that wraps your microservice.\n\n## Now Let's Scale the GraphQL Microservice !\nThe proxy knows how to reference the same images with a round robin loadbalancer. \n\nGo in the folder where the SWAPI docker-compose file is. \n\nEnter the command: \n```sudo docker-compose scale swapi=3```\n\nThe proxy will automatically start a loadbalancer\n\n\n**And thats all!**\nNow you can add you Graphql microservices by adding the labels to your compose file and set the same Network (for example 'web').\n\n\n# Run with Kubernetes (18min example)\n\nIt will use the Kubernetes API to find available GraphQL Endpoints. \n\nGeneral use is the same like docker. \nSee [how it works with Docker](#runWithDocker).\nYou have to set labels in the Deployment-Manifest.\n\n- ```kubernetesConfigurationKind```: How the proxy find the Kubernetes API. \n  - ```fromKubeconfig```: A Config file which is mount in the Container\n  - ```getInCluster```: The POD as it self.\n  - ```getInClusterByUser```: The POD as it self but with a spezial self set user \n\n([example Configurations](#possibleK8sCombinations))\n\n([also see this full configuration description ](#availableEndpoints))\n\n\n([see ./example/kubernetes](/example/kubernetes)).\n\n## The Yaml for the GraphQL Proxy:\n\nDeployment.yaml\n```\napiVersion: extensions/v1beta1\nkind: Deployment\nmetadata:\n  annotations:\n    kompose.cmd: kompose convert\n    kompose.version: 1.13.0 (84fa826)\n  creationTimestamp: null\n  labels:\n    io.kompose.service: api\n  name: api\n  namespace: gqlproxy\nspec:\n  replicas: 1\n  strategy: {}\n  template:\n    metadata:\n      creationTimestamp: null\n      labels:\n        io.kompose.service: api\n    spec:\n      containers:\n      - env:\n        - name: gqlProxyToken\n          value: \"1234\"\n        - name: kubernetesConfigurationKind\n          value: getInCluster\n        - name: qglProxyRuntime\n          value: kubernetesWatch\n        image: fasibio/graphqldockerproxy\n        name: api\n        ports:\n        - containerPort: 3000\n        resources: {}\n      restartPolicy: Always\nstatus: {}\n\n---\nkind: Service\napiVersion: v1\nmetadata:\n  labels:\n    name: api\n  name:      api\n  namespace: graphqlproxy\nspec:\n  ports:\n    - port: 3000\n      targetPort: 3000\n      name: http\n  selector:\n    app: api\n\n```\n\n\n## The Yaml for the GraphQL (SWAPI)\n\nHere it is importend that the ```service``` have the ```annotations``` \n  - ```gqlProxy.token```: The same token you set in the proxy. (In this example 1234)\n  - ```gqlProxy.url```: This is the relative path to the proxy running inside the container. (For example: :9000/graphql)\n  - ```gqlProxy.namespace```: The namespace that wraps your microservice queries.\n\n\n```\n---\nkind: Deployment\napiVersion: extensions/v1beta1\nmetadata:\n  \n  labels:\n    app:     swapi\n  name:      swapi\n  namespace: starwars\nspec:\n  minReadySeconds: 20\n  replicas: 2\n  revisionHistoryLimit: 32\n  template:\n    metadata:\n      name: swapi\n      labels:\n        app: swapi\n    spec:\n      terminationGracePeriodSeconds: 1\n      containers:\n        - image: bfillmer/graphql-swapi\n          imagePullPolicy: Always\n          name: swapi\n          ports:\n            - containerPort: 9000\n              name: http-port\n---\nkind: Service\napiVersion: v1\nmetadata:\n  annotations:\n    gqlProxy.token: '1234'\n    gqlProxy.url: ':9001/graphql'\n    gqlProxy.namespace: 'swapi'\n  labels:\n    name: swapi\n  name:      swapi\n  namespace: starwars\nspec:\n  ports:\n    - port: 9001\n      targetPort: 9000\n      name: http\n  selector:\n    app: swapi\n\n```\n\nThats it ! Now you have the API running under Kubernetes. \n\n## All About Namespaces\u003ca name=\"allAboutNamespaces\"\u003e\u003c/a\u003e\nNamespaces are set by the GraphQl backend microservice, with the label ```gqlProxy.namespace```.\nIf you need more than one GraphQL backend server in the same namespace, then give the same name in the label ```gqlProxy.namespace```. The proxy will merge the services. \n\n\n### WARNING!!!!\nAt the moment it's not possible to have same queries, mutations or types for different entities. The proxy will use the first one it finds. \n\n\n# Admin page / Metadata Page\n\nTo see what the proxy has included and there is another graphql service under ```/admin/graphql``` as well. \nHere you can see all of the namespaces and endpoint metadata for the included proxy nodes.\nIf an endpoint being served by a loadbalancer, then you can also find the \"real\" endpoints. \n\nSet the environment variables, ```gqlProxyAdminUser``` and ```gqlProxyAdminPassword```, to configure a Basic Auth for the admin page.\n\n## Available Environments for the GraphQL Proxy\u003ca name=\"availableEndpoints\"\u003e\u003c/a\u003e\n\nKey | Available Values | Default | Description | Need for | Required \n--- | --- | --- | --- | --- | ---\n| ```qglProxyRuntime``` |  ```dockerWatch``` or  ```kubernetesWatch``` | ```dockerWatch``` | tells the proxy run to in a docker image or in a kubernetes \"world\" | docker and kubernetes | true \n|```dockerNetwork``` | string | none | the network where the backend GraphQL-Server is shared with the proxy|  ```dockerWatch```| for docker\n| ```gqlProxyToken``` | string | empty string | a token which verifies that the microservice belongs to the proxy |  ```dockerWatch``` or ```kubernetesWatch``` | false but better you set it\n|```kubernetesConfigurationKind``` | ```fromKubeconfig``` or ```getInCluster``` or ```getInClusterByUser``` | ```fromKubeconfig``` | How the proxy finds the Kubernetes API config. | ```kubernetesWatch``` | false\n|```gqlProxyPollingMs```| int | 5000 | The polling time to check for changes (send introspection Query) |  all | false\n|```gqlProxyK8sUser```| string | no Default | The K8s user. This is only needed for configuration type ```getInClusterByUser```. |  ```kubernetesWatch``` | false\n|```gqlProxyK8sUserPassword```| string | no Default |  The password for the K8s user. This is only needed for configuration type ```getInClusterByUser```. |  ```kubernetesWatch``` | false\n|```gqlProxyAdminUser```| string | empty string | The Basic Auth user for the admin page |  all | false\n|```gqlProxyAdminPassword```| string | empty string | The Basic Auth password for the admin page |  all | false\n|```gqlShowPlayground```| bool | true | toggle graphql playground ui on and off |  all | true\n|```gqlBodyParserLimit```| string| 1mb | Set the body size limit for big Data | all | false\n|```winstonLogLevel```| string| ```info``` | Set standart loglevel for winston e.g: ```debug```, ```info```, ```warn``` ```error``` | all | false\n|```winstonLogStyle```| string| ```simple``` | Set the style to logging for winston ```simple``` or ```json``` | all | false\n|```enableClustering```| bool | ```false``` | Staring a cluster set a proxy for each cpu kernel. (sometimes can bring more boost) | all | false\n|```sendIntrospection```|bool | ```true```| if it true: client can see the structure. if it false: no introspection will be send. **For more __security__ Set to false in Produktion mode** | all| false\n|```gqlApolloEngineApiKey```|string| empty string | The apollo Engine Key (after login by apollo you get this key)|all| false\n### Possible Environment Variable Combinations for Docker\n  - ```qglProxyRuntime```=dockerWatch\n  - ```dockerNetwork```=web\n\n\n\n ## Available Labels/Annotations for all GraphQL Endpoints\n\nKey | Available Values |  Description | Required \n--- | --- | --- | --- \n| ```gqlProxy.token``` |string | The same token you set in the proxy. (In this example 1234) | true \n|```gqlProxy.url``` | string |  This is the relative path to the proxy running inside the container. (For example: :9000/graphql)| true\n| ```gqlProxy.namespace``` | string  | The namespace that wraps your microservice.  See [\"All About Namespaces\"](#allAboutNamespaces) for more information| true\n\n\n### Possible Environment Variable Combinations for Kubernetes\u003ca name=\"possibleK8sCombinations\"\u003e\u003c/a\u003e\n\n### Watching: \n  #### For a User in the Pod\n  - ```qglProxyRuntime```=kubernetesWatch\n  - ```kubernetesConfigurationKind```=getInCluster\n\n  #### For an Explicit User\n  - ```qglProxyRuntime```=kubernetesWatch\n  - ```kubernetesConfigurationKind```=getInClusterByUser\n  - ```gqlProxyK8sUser```=myK8sUser\n  - ```gqlProxyK8sUserPassword```=thePassword\n\n### For All of the Above\n  - ```gqlProxyPollingMs```=10000\n  - ```gqlProxyAdminUser```=myAdminPageUser\n  - ```gqlProxyAdminPassword```=adminPassword\n \n # and finally\n \n If you find a bug, have questions please open an issue. \n \n Have fun.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffasibio%2Fgraphqldockerproxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffasibio%2Fgraphqldockerproxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffasibio%2Fgraphqldockerproxy/lists"}