graphql-docker-api

GraphQL Docker API

A GraphQL Server for the Docker API, written in Golang.

GraphQL Schema

• Schema files can be found here.
• You can check the query-ready fields in the TODO list

Note: It's important to keep this schema synced with the types implemented in the wrapper, best efforts are made in order to keep it so. That being said, You need to know this schema is subject to change as the time goes by and new changes are introduced in the Docker API and this wrapper as well.

Getting Started

Building from source

• Get the package: go get -d gitlab.com/klud/graphql-docker-api/cmd/gdapi
• Dependencies
  • Not using dep. Go to the project folder with cd $GOPATH/src/gitlab.com/klud/graphql-docker-api/cmd/gdapi and go get -d ./, this will download the depedencies needed, once that's done build the package with go build.
  • Using dep. Go to the project folder with cd $GOPATH/src/gitlab.com/klud/graphql-docker-api, and run dep ensure, now get to $GOPATH/src/gitlab.com/klud/graphql-docker-api/cmd/gdapi and build the package with go build.

That's pretty much it. Congrats You have GraphQL Docker API on your system now.

Docker image

Local socket

docker run -d \
--name docker-gql \
-p 8080:8080 \
-e API_ENDPOINT="/api" \
-v /var/run/docker.sock:/var/run/docker.sock \
klud/docker-gql

Note: The -v /var/run/docker.sock:/var/run/docker.sock option can be used in Linux environments only.

Remote host

docker run -d \
--name docker-gql \
-p 8080:8080 \
-e API_ENDPOINT="/api" \
-e DOCKER_HOST="http://<host>:<port>" \
klud/docker-gql

docker run -d \
--name docker-gql \
-p 8080:8080 \
-e API_ENDPOINT="/api" \
-e DOCKER_HOST="https://<host>:<port>" \
-v /path/to/folder/containing/the/docker/certs:/etc/docker \
klud/docker-gql

Environment variables

• DOCKER_CERT_PATH: When using safe connection to Docker Remote API.
• DOCKER_HOST: Host the API will retrieve information from (default: "/var/run/docker.sock").
• GQL_PORT: Port the API will listen on (default: ":8080").
• GRAPHIQL: It's enabled by default, GRAPHIQL=0 must be set in order to disable it.
• API_ENDPOINT: Endpoint for the API (default: "/graphql").

Notes

• If using a Docker Remote API, this must be specified with the either HTTP or HTTPS protocols (e.g,: DOCKER_HOST="http://<host>:<port>").
• When using HTTPS, the TLS certs must be placed in /etc/docker or the /path/to/folder/containing/the/docker/certs must be mounted under /etc/docker inside the running container, and must follow the semantics behind the DOCKER_CERT_PATH env var.
• GRAPHIQL can be reached at the API_ENDPOINT; disabling is advised when using in production, you can do so by setting GRAPHIQL=0.

TODO

• GraphQL Queries
  • Map to endpoints of the Docker API
    • Containers
    • Images
    • Swarm
      • Services
      • Stacks
    • System
    • Volumes
    • Secrets
    • Tasks
• GraphQL Mutations
• GraphQL Subscriptions if possible, especially for Docker events
• GraphQL Descriptions
• Authentication / Authorization
• Makefile for local build
  • Binary
  • Docker image
• CI integration
• Build from source how-to
• Docker image how-to
  • Multiarch support using manifest-tool

Open-Source libraries and tools

• docker/client
• golang/dep
• gorilla/mux
• neelance/graphql-go
• urfave/negroni