The Engine Proxy has many configuration options. While all you need to set to get started is your apiKey, many aspects of the Proxy’s behavior can be fine-tuned. This page describes all the available options.

If you are using the apollo-engine npm package, the parameters described here are the options to the new ApolloEngine and new ApolloEngineLauncher constructors. If you are using the Docker container distribution, the parameters described here go into your engine-config.json file.

The ApolloEngine class in the apollo-engine npm package takes care of filling in a few important parameters for you automatically: frontends.host, frontends.port, frontends.endpoints, origins.http.url, and origins.http.useFrontendPath. If you are using that class, all you need is your apiKey to get started (which can also be set with the ENGINE_API_KEY environment variable).

All Durations are represented as strings consisting of a number of seconds followed by the letter s, such as "30s" or ".5s".

Top level options

These are the top-level options for the new ApolloEngine() or new ApolloEngineLauncher() constructors or for the engine-config.json file.

apiKey (string)

API key for the service. Get this from Engine by logging in and creating a service. You may also specify this with the ENGINE_API_KEY environment variable; the config file takes precedence. Required.

origins (array of Origin)

Origins represent the GraphQL servers to which the Proxy will send requests. If you’re using the ApolloEngine class from the apollo-engine npm package, you don’t need to specify origins: the package will generate one automatically for you, or will fill in the url automatically if you have configured other origin properties. Otherwise this field is required.

frontends (array of Frontend)

Frontends represent the HTTP servers that the Proxy creates to listen for GraphQL queries. If not specified, a frontend will be created with default values.

stores (array of Store)

The list of configured stores to cache responses to.

sessionAuth (SessionAuth)

The session authorization configuration to use for per-session caching.

logging (Logging)

The logging configuration to use.

reporting (Reporting)

The reporting configuration to use.

queryCache (QueryResponseCache)

Configuration for caching responses to GraphQL queries. Only responses annotated with the cache-control extension are cached.

persistedQueries (PersistedQueries)

Configuration for persisted queries.

debugServer (DebugServer)

Configuration for an HTTP server which can be used to debug the Proxy. If you enable the debug server in production, you should ensure that its port is not publicly accessible, as it provides internal information about the Proxy.

DebugServer

DebugServer configures an HTTP server which can be used to debug the Proxy. If you enable the debug server in production, you should ensure that its port is not publicly accessible, as it provides internal information about the Proxy. The server includes the Go pprof profiler. Apollo support may direct you to enable this server, and send them the files created by commands such as wget http://127.0.0.1:4444/debug/pprof/profile.

host (string)

The address on which to listen. If left blank, this will default to “127.0.0.1”; set to “0.0.0.0” to listen on all interfaces.

port (int32)

The port on which to listen. Required.

Frontend

Frontend defines a web server run by the Proxy. The Proxy will listen on each frontend for incoming GraphQL requests.

host (string)

The address on which to listen. If left blank, this will default to all interfaces. (If you are using the ApolloEngine class from the apollo-engine npm module, this field defaults to the host option of the engine.listen method.)

port (int32)

The port on which to listen. If left blank, this will attempt to use the port specified in portFromEnv. If portFromEnv is left blank, this will select a random available port. (If you are using the ApolloEngine class from the apollo-engine npm module, this field defaults to the port option of the engine.listen method.) Only one of port, portFromEnv, and pipePath may be set.

pipePath (string)

The pipe to the path to listen on. Engineproxy can listen on a named pipe on a Windows OS instead of over TCP. Only one of port, portFromEnv, and pipePath may be set.

portFromEnv (string)

The name of the environment variable to use for choosing port, usually “PORT”. For example, when using a Docker container deployed on Heroku, you should NOT set port, and set portFromEnv to be PORT. See the Engine docs for a more detailed walkthrough on setting up Apollo Engine on Heroku and similar hosting platforms. Only one of port, portFromEnv, and pipePath may be set.

endpoints (array of string)

URL paths on which to listen; often ["/graphql"]. (If you are using the ApolloEngine class from the apollo-engine npm module, this field defaults to the graphqlPaths option of the engine.listen method, which itself defaults to ["/graphql"].)

originName (string)

Name of origin to serve with this frontend. The Proxy will also pass any HTTP requests sent to paths not in endpoints to this origin. If not defined, defaults to the empty string, which is a valid origin name.

endpointMap (map<string, string>)

Map from URL path to origin name. Use this field instead of endpoints and originName if you want different URL paths on this frontend to serve different origins. If you use this field, the Proxy will return a 404 error to HTTP requests sent to paths that don’t match one of its keys.

overrideGraphqlResponseHeaders (map<string, string>)

If set, HTTP responses from this frontend will have these headers added (or replaced) with the given values. These headers are only applied to GraphQL responses, not Websockets or HTTP processes outside of GraphQL paths. One use case for this is ensuring that CORS response headers are set for all GraphQL responses, including those generated by Engine itself without talking to your backend as part of the persistent query protocol. See also overrideRequestHeaders (on Origin).

extensions (Frontend.Extensions)

Configuration for GraphQL response extensions.

responseCompression (Frontend.ResponseCompression)

Configuration for compressing GraphQL responses if requested by the client via the HTTP Accept-Encoding header.

tls (Frontend.TLS)

Configuration for TLS/HTTPS termination by the proxy.

Frontend.Extensions

Configuration for GraphQL response extensions.

strip (array of string)

Extensions to strip from responses returned to clients. Clients may still request these extensions, use blacklist for stronger protection. If not specified, defaults to all Apollo extensions: ["cacheControl","tracing"]

blacklist (array of string)

Extensions to always strip, even if the client requests them. If not specified, defaults to Apollo tracing extension: ["tracing"]

Frontend.ResponseCompression

Configuration of GraphQL response compression.

disabled (bool)

By default, Engine will respect the Accept-Encoding HTTP header and use compression if gzip is supported by its client. Set this to true to ignore Accept-Encoding: gzip. This is independent of disabling compression when Engine sends GraphQL queries to your origin, which is configured in http.disableCompression on your Origin. Engine will never proactively compress responses to requests on non-GraphQL paths but will pass through any compression applied by the server it is proxying to.

minSizeToCompress (int32)

By default, Engine will not compress responses that are less than 1400 bytes. Set this option to change that threshold.

compressionLevel (int32)

Set this to a number from 1 to 9 to change the gzip compression level, where 1 is the fastest and 9 produces the smallest outputs. The default is 6.

Frontend.TLS

Configuration for TLS/HTTPS connections. TLS configuration can not be changed at runtime.

certificateFile (string)

Path to a file containing a PEM-encoded public certificate, followed by any intermediate certificates.

keyFile (string)

Path to a file containing a PEM-encoded private key.

redirectFromUnencryptedPorts (array of int32)

Additional ports to spawn HTTP listeners that automatically redirect to HTTPS. If you wish to serve both HTTP and HTTPS traffic, create multiple frontends. Note that all redirects go to the domain in the incoming request’s Host header without a specified port, not to the port that this frontend is listening on, because we assume that all end-user HTTPS requests are going across the network on port 443.

Logging

The logging configuration.

level (string)

Log level for the Proxy. Defaults to “INFO”. Set to “DEBUG” for more verbose logging or “ERROR” for less verbose logging.

format (Logging.LogFormat)

Log format for the proxy. Defaults to TEXT.

destination (string)

Path for logs. Can be a file path, STDOUT or STDERR.

request (Logging.AccessLogging)

Configuration for request logging, which logs every HTTP request (including non-GraphQL).

query (Logging.AccessLogging)

Configuration for query logging, which logs only GraphQL queries.

Logging.AccessLogging

Configuration for access logging.

destination (string)

Path for JSON access logs of all proxy traffic. Can be a file path, STDOUT or STDERR.

requestHeaders (array of string)

Request headers to include in access logs.

responseHeaders (array of string)

Response headers to include in access logs.

Origin

An Origin is a backend that the Proxy can send GraphQL requests to. Can use one of:

  1. HTTP / HTTPS

  2. AWS Lambda

requestTimeout (Duration, a string like “4.5s”)

Amount of time to wait before timing out request to this origin. If this is left unspecified, it will default to 30 secs for HTTP or use the function’s timeout for Lambda.

maxConcurrentRequests (uint64)

Maximum number of concurrent requests to the origin. All requests beyond the maximum will return 503 errors. If not specified, this will default to 9999.

requestType (Protocol)

The type of the body of a request to this origin. If not specified, will default to JSON.

supportsBatch (bool)

Does this origin support batched query requests, as defined by: https://github.com/apollographql/apollo-server/blob/213acbba/docs/source/requests.md#batching

http (Origin.HTTP)

Configuration if this is an HTTP origin. Specify at most one of this and lambda. If neither are specified, this defaults to an HTTP origin with no specific configuration.

lambda (Origin.Lambda)

Configuration if this is a Lambda origin. Specify at most one of this and http.

name (string)

The name of the origin; used in other parts of the config file to reference the origin. Empty strings are valid. If not defined, defaults to the empty string.

Origin.HTTP

Configuration for forwarding GraphQL queries to an HTTP endpoint.

url (string)

The backend server’s GraphQL URL. Required unless using the ApolloEngine class from the apollo-engine npm module.

When forwarding requests to your backend server, Engine will preserve the client’s original Host header. If you are setting url manually to a GraphQL server hosted on shared infrastructure which relies on the Host header, you should use the overrideRequestHeaders field to set Host to your backend server’s hostname. This is not relevant when this field is set automatically by ApolloEngine or when it is set to localhost or an IP address.

useFrontendPath (bool)

If set, the path (endpoint) from the frontend’s URL will be appended to this origin’s URL. This allows you to set up just one Origin for an HTTP host with multiple paths serving GraphQL, by specifying multiple endpoints on the frontend. Set automatically if ApolloEngine is filling in the url field for you.

disableCompression (bool)

If set, requests to this origin will not attempt to use gzip compression. This is usually a performance improvement if engine is running on the same server as the origin. (To control whether Engine will compress GraphQL responses on the way back to the client, see the responseCompression field on Frontend.)

maxIdleConnections (uint64)

Maximum number of idle connections to keep open. If not specified, this will default to 100.

trustedCertificates (string)

File path to load trusted X509 CA certificates. This should not be required if your HTTPS origin works in modern browsers. Certificates must be PEM encoded, and multiple certificates can be concatenated into a single file. If specified, only servers with a trust chain to these certificates will be accepted. If not specified, this will default to a certificate bundle included with the proxy binary, which is extracted from Ubuntu Linux.

disableCertificateCheck (bool)

If set, X509 certificate validity (issuer, hostname, expiration) is not verified. This is very insecure, and should only be used for testing.

overrideRequestHeaders (map<string, string>)

If set, requests to this origin will have these headers replaced (or added) with the given values. See also overrideGraphqlResponseHeaders (on Frontend).

Origin.Lambda

Configuration for proccessing GraphQL queries in an AWS Lambda function.

functionArn (string)

The handler function’s ARN (formatted as “arn:aws:lambda:REGION:ACCOUNT-ID:function:FUNCTION-NAME”). Required.

awsAccessKeyId (string)

The AWS access key ID for an AWS IAM user with lambda:Invoke permissions. If this is left unspecified, it will fall back to environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, then to EC2 instance profile.

awsSecretAccessKey (string)

The AWS secret access key for the AWS IAM access key ID specified in the awsAccessKeyId field.

PersistedQueries

PersistedQueries defines behaviour of the persistent query cache.

store (string)

The name of the store to use in caching queries, or “disabled” to not support automatic persisted queries.

compressionThreshold (int64)

Minimum size in bytes to trigger compression. If not specified, defaults to 1024. Set to a negative number to disable compression.

QueryResponseCache

QueryResponseCache defines the behaviour of the query response cache.

publicFullQueryStore (string)

The name of the store (by default, the empty string) to use in caching full query responses containing only public/shared data, or “disabled” to not cache public full query responses. Only responses annotated with the cache-control extension are cached.

privateFullQueryStore (string)

The name of the store (by default, the empty string) to use in caching full query responses containing only private/per-session data, or “disabled” to not cache private full query responses. Only responses annotated with the cache-control extension are cached, and this is ignored unless the sessionAuth field is specified.

Reporting

The reporting configuration to use. Reports about the GraphQL queries and responses will be sent approximately every 5 seconds to the endpointUrl.

endpointUrl (string)

URL to send the reports to. By default, reports will be sent to “https://engine-report.apollodata.com”.

maxAttempts (int32)

Reporting is retried with exponential backoff, up to this many times. This is inclusive of the original request. Must be at least zero.

retryMinimum (Duration, a string like “4.5s”)

Minimum backoff for retries. If not specified this will default to 100ms. Must be greater than 0.

retryMaximum (Duration, a string like “4.5s”)

Maximum backoff for retries. Must be greater than or equal to retryMinimum.

debugReports (bool)

Dump reports as JSON to debug logs. This is usually only used by Apollo support.

hostname (string)

Override for hostname reported to backend.

noTraceVariables (bool)

Don’t include variables in query traces.

noTraceErrors (bool)

Disable sending error traces to Apollo servers. Errors are still returned in responses, but not reported to Apollo Engine cloud storage. This is for special cases when errors contain PII.

privateHeaders (array of string)

Headers that should not be sent to Apollo servers. These are case-sensitive.

proxyUrl (string)

URL to proxy reporting requests through. socks5:// and http:// proxies are supported.

privateVariables (array of string)

Names of variables whose values should not be sent to Apollo servers. These are case-sensitive.

disabled (bool)

Disable sending all reports to Apollo servers.

SessionAuth

SessionAuth describes how the Proxy identifies clients for private cache responses. Optionally, it can tell the Proxy how to authenticate sessions.

header (string)

The header that contains an authentication token. Set either this field or “cookie”.

cookie (string)

The cookie that contains an authentication token. Set either this field or “header”.

tokenAuthUrl (string)

The URL to use in validating the session authentication token. The Proxy will submit an HTTP POST to this URL with a JSON body containing: {"token": "AUTHENTICATION-TOKEN"}. The response body should return an integer field “ttl” specifying the number of seconds to continue to consider the session to be valid, and an optional “id” field specifying a longer lived user identifier. This “id” allows the cache to span logins and/or user devices. {"ttl": 300, "id": "user1"} This url must respond with an HTTP 2xx for valid authentication tokens. If the returned “ttl” is 0, or no “ttl” is provided, the session is considered valid forever. If the response is an HTTP 401 or 403, or the returned “ttl” is < 0, the session is considered invalid and the request is rejected by the Proxy.

store (string)

The name of the store (by default, the empty string) to use for caching the sessionIDs that have been verified, or “disabled” to not cache verified sessionIDs. (This field is ignored unless tokenAuthUrl is set.)

Store

Configures a cache for GraphQL and authentication responses. Can use one of:

  1. memcached

  2. in-memory cache

By default, there exist an in-memory store with the default size and the empty string as a name, which is used by all features that use a store unless they specify a different store name or “disabled”.

name (string)

The name of the store; used in other parts of the config file to reference the store. May be the empty string.

memcache (Store.Memcache)

Memcache configuration. Specify at most one of this and inMemory.

inMemory (Store.InMemory)

In-memory configuration. Specify at most one of this and memcache. If neither are specified, this defaults to an in-memory cache with no specific configuration.

Store.InMemory

Configures in-memory store.

cacheSize (int64)

The size of the in-memory cache in bytes. Must be greater than 512KB. If not specified, will be 50MB. Note that only values smaller than approximately 1/1024th of the in memory cache size are stored. You’ll see WARN logs if values are overflowing this limit. Changing this value after the proxy has launched will invalidate the current cache.

Store.Memcache

Configures memcached store

url (array of string)

Addresses (hostname:port) of memcached servers.. Currently does not support authentication.

timeout (Duration, a string like “4.5s”)

Socket read/write timeout for the store. This will default to 1s if not specified.

keyPrefix (string)

A prefix added to every memcached key. This allows you to share a single memcached cluster between multiple unrelated Apollo Engine Proxy configurations, or with other data.

Edit on GitHub
// search box