Docker

Docker is a tool that allows you to package an application and its dependencies into a container that can run on any system. This makes it easy to deploy applications in a consistent and reproducible way, regardless of the underlying infrastructure.

To simplify running GraphQL Mesh, you can use the Docker image and the Docker Compose template we provide. This setup allows you to easily configure and run the gateway without the need to install Node.js and the required mesh npm packages.

Prerequisites

Make sure you have Docker installed on your system.

You can follow the official Docker Engine install manual in case you don’t have Docker installed already.

Configuration

Arguments

Mesh Serve can be configured with CLI arguments even when running the image!

For example, changing the supergraph to use the my-schema.graphql schema instead looks like this:

docker run \
  -p 4000:4000 \
  -v "$(pwd)/my-schema.graphql:/serve/my-schema.graphql" \
  ghcr.io/ardatan/mesh-serve --supergraph=my-schema.graphql

For a full list of CLI arguments, please refer to the CLI arguments.

Config File

Instead of configuring Mesh Serve with CLI arguments, we support configuring with a config file.

You’re recommended to use the mesh.config.ts file to configure Mesh Serve. Simply mount the config file when running the image.

mesh.config.ts

import { defineConfig } from '@graphql-mesh/serve-cli'
 
export const serveConfig = defineConfig({
  proxy: {
    endpoint: 'https://example.com/graphql'
  }
})

docker run \
  -p 4000:4000 \
  -v "$(pwd)/mesh.config.ts:/serve/mesh.config.ts" \
  ghcr.io/ardatan/mesh-serve

For a full list of CLI arguments, please refer to the Config Reference.

Changing Port in Container

The default port where Mesh Serve listens is 4000; however, maybe the container is running inside a network (like when using Networking in Compose) and you wish to change the port of Mesh Serve in the image.

You can use the mesh.config.ts to change the port, or simply pass in the --port argument when running the image:

docker run \
  -p 8080:8080 \
  -v "$(pwd)/supergraph.graphql:/serve/supergraph.graphql" \
  ghcr.io/ardatan/mesh-serve --port=8080

Running

Having a supergraph.graphql already composed with Mesh Compose, running the Docker image is as easy as:

docker run \
  -p 4000:4000 \
  -v "$(pwd)/supergraph.graphql:/serve/mesh.config.ts" \
  ghcr.io/ardatan/mesh-serve

Docker Compose

You may have an environment where you want to use Docker Compose and would like to add Mesh Serve there.

Start by defining the docker-compose.yml

services:
  mesh-serve:
    image: ghcr.io/ardatan/mesh-serve
    ports:
      - '4000:4000'
    # Add GraphQL Hive environment variables in case you use it
    # environment:
    #   HIVE_CDN_ENDPOINT: <secret>
    #   HIVE_CDN_KEY: <secret>
    #   HIVE_REGISTRY_TOKEN: <secret>
    volumes:
      - ./mesh.config.ts:/serve/mesh.config.ts

And then simply start the services with:

docker compose up

Extend Docker Image

Install Plugin

You may want to add additional functionality, or plugins to the base image - you just need to create a new Dockerfile basing the image off ghcr.io/ardatan/mesh-serve.

If need only a handful of plugins (or some other dependencies), you can simply extend the image and install the modules with npm i:

For example, adding Rate Limiting to the container would look like this:

Dockerfile

FROM ghcr.io/ardatan/mesh-serve
 
RUN npm i @graphql-mesh/plugin-rate-limit

docker build -t mesh-serve-w-rate-limit .

Configure to use the rate limiting plugin:

mesh.config.ts

import useRateLimit from '@graphql-mesh/plugin-rate-limit'
import { defineConfig } from '@graphql-mesh/serve-cli'
 
export const serveConfig = defineConfig({
  plugins: pluginCtx => [
    useRateLimit({
      ...pluginCtx,
      rules: [
        {
          type: 'Query',
          field: 'foo',
          max: 5, // requests limit for a time period
          ttl: 5000, // time period
          // You can use any value from the context
          identifier: '{context.headers.authorization}'
        }
      ]
    })
  ]
})

And then simply start the new image with the config file mounted:

docker run \
  -p 4000:4000 \
  -v "$(pwd)/mesh.config.ts:/serve/mesh.config.ts" \
  mesh-serve-w-rate-limit

Develop Plugin

However, you may be developing a plugin and have a setup with some dependencies and source code, copying over your project’s files is the way to go.

In the following example, we’re developing a useTiming plugin that will add a human readable execution duration to the GraphQL result extensions property.

package.json

{
  "name": "my-timing",
  "dependencies": {
    "moment": "^2"
  },
  "devDependencies": {
    "@graphql-mesh/serve-cli": "latest",
    "@graphql-mesh/serve-runtime": "latest"
  }
}

my-timing.ts

import moment from 'moment'
import type { MeshServePlugin } from '@graphql-mesh/serve-runtime'
 
export function useTiming(): MeshServePlugin {
  return {
    onExecute() {
      const start = Date.now()
      return {
        onExecuteDone({ result, setResult }) {
          const duration = moment.duration(Date.now() - start)
          if (isAsyncIterable(result)) {
            setResult(
              mapAsyncIterator(result, result => ({
                ...result,
                extensions: {
                  ...result?.extensions,
                  duration: duration.humanize()
                }
              }))
            )
            return
          }
          setResult({
            ...result,
            extensions: {
              ...result?.extensions,
              duration: duration.humanize()
            }
          })
        }
      }
    }
  }
}

mesh.config.ts

import { defineConfig } from '@graphql-mesh/serve-cli'
import { useTiming } from './my-timing'
 
export const serveConfig = defineConfig({
  plugins: () => [useTiming()]
})

Your Dockerfile should then look something like this:

Dockerfile

FROM ghcr.io/ardatan/mesh-serve
 
# we dont install dev deps because:
#   1. we need them for type checking only
#   2. Mesh Serve is already available in the docker image
COPY package*.json .
RUN npm i --omit=dev
 
COPY my-time.ts .
COPY mesh.config.ts .

Then build your image:

docker build -t mesh-serve-w-my-timing .

And finally start it (the config file is in the image and doesn’t need to be mounted):

docker run -p 4000:4000 mesh-serve-w-my-timing

💡

For faster development, you can mount the source code as volumes so that you don’t have to rebuild the image on each run.

docker run -p 4000:4000 \
  -v "$(pwd)/mesh.config.ts":/serve/mesh.config.ts \
  -v "$(pwd)/my-timing.ts":/serve/my-timing.ts \
  mesh-serve-w-my-timing

Additional Resolvers

Instead maybe you need to define additional resolvers that depend on other dependencies. Similarily to the Develop Plugin approach, you can just copy the project code over and build another image.

Say you have the following files:

package.json

{
  "name": "my-time",
  "dependencies": {
    "moment": "^2"
  },
  "devDependencies": {
    "@graphql-mesh/serve-cli": "latest"
  }
}

my-time.ts

import moment from 'moment'
 
export const additionalResolvers = {
  Query: {
    formattedToday() {
      return moment().format('DD.MM.YYYY')
    }
  }
}

mesh.config.ts

import { defineConfig } from '@graphql-mesh/serve-cli'
import { additionalResolvers } from './my-time'
 
export const serveConfig = defineConfig({ additionalResolvers })

Your Dockerfile should then look something like this:

Dockerfile

FROM ghcr.io/ardatan/mesh-serve
 
# we dont install dev deps because:
#   1. we need them for type checking only
#   2. Mesh Serve is already available in the docker image
COPY package*.json .
RUN npm i --omit=dev
 
COPY my-time.ts .
COPY mesh.config.ts .

Then build your image:

docker build -t mesh-serve-w-add-res .

And finally start it (the config file is in the image and doesn’t need to be mounted):

docker run -p 4000:4000 mesh-serve-w-add-res

Overview Introduction