A local GraphQL server can work perfectly and still fail after release. Production adds authentication, traffic limits, secrets, schema changes, database pressure, and incomplete monitoring.
The safest way to deploy GraphQL API services is to treat the endpoint as a controlled production system, not another application route. You need a repeatable build, restricted access, query protection, useful telemetry, and a rollback path.
DEFINE THE PRODUCTION CONTRACT FIRST
Before you deploy GraphQL API code, write down what the service must support and what it must reject. This prevents deployment decisions from being based on local development defaults.
Confirm the endpoint behavior
Define these values before creating the container or cloud service:
- GraphQL endpoint, such as
/graphql - Health endpoint, such as
/healthz - Required authentication method
- Allowed browser origins
- Maximum request body size
- Maximum query depth or complexity
- Maximum page size for list fields
- Expected timeout for database and upstream calls
- Public and private schema operations
Use the GraphQL.js production guidance as a baseline, then add limits that match your database and traffic patterns.
A production contract should also state what happens when a dependency fails. A database timeout should return a controlled GraphQL error. It shouldn’t expose a connection string, SQL statement, stack trace, or internal service name.
Separate development from production
Development needs a fast feedback loop. Production needs predictable behavior.
In development, you can allow local introspection, detailed errors, a browser landing page, and broad CORS settings. In production, use explicit origins, restricted introspection, masked internal errors, small request limits, and secrets supplied by the deployment platform.
Keep separate environment values for development, staging, and production. Don’t copy a local .env file into a container image. Store production secrets in the cloud secret manager or deployment platform, then inject them at runtime.
HOW TO DEPLOY GRAPHQL API CODE IN A CONTAINER
A container gives you a repeatable artifact. The same image can run in a local test environment, staging, and production.
Install only the packages your server needs. A typical Node.js Apollo setup may use:
npm install @apollo/server graphql express cors
npm install --save-dev typescript
Your exact integration package depends on the Express version and framework adapter. Lock the dependency tree with package-lock.json, and use npm ci in the build process.
Build a small, non-root image
A basic Dockerfile can look like this:
FROM node:22-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
RUN npm prune --omit=dev
FROM node:22-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/package*.json ./
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
USER node
EXPOSE 4000
CMD ["node", "dist/server.js"]
Use the Node.js version approved by your team. The important controls are dependency locking, a production build, removal of development dependencies, a non-root process, and no secrets inside the image.
Add a .dockerignore file that excludes .git, .env files, local logs, test output, and node_modules. Scan the image before release. Reject images with critical vulnerabilities unless the security owner has documented an exception.
Select the runtime around your workload
A managed container service is usually the shortest path for a small team. AWS App Runner supports deployment from source code or a container image and provides managed Node.js runtime options. Its Node.js platform documentation covers build and start commands.
Other teams use Cloud Run, a container service from another cloud provider, or Kubernetes. The choice depends on traffic patterns, network requirements, deployment controls, and the team’s operating experience.
Use a managed platform when you need a public API without managing cluster operations. Use Kubernetes when you already need cluster-level scheduling, service networking, custom ingress, or multiple internal workloads. Don’t choose Kubernetes only because the API is important. It adds operational work.
CONFIGURE THE NODE.JS SERVER FOR PRODUCTION
Your server should listen on the port supplied by the platform. It should also expose a health route that doesn’t require a GraphQL query.
A simplified Express and Apollo arrangement looks like this:
const isProduction = process.env.NODE_ENV === "production";
const server = new ApolloServer({
schema,
introspection: !isProduction,
plugins: isProduction
? [ApolloServerPluginLandingPageDisabled()]
: []
});
app.get("/healthz", (req, res) => {
res.status(200).json({ status: "ok" });
});
app.use(
"/graphql",
cors({
origin: process.env.ALLOWED_ORIGIN,
credentials: true
}),
express.json({ limit: "100kb" }),
expressMiddleware(server, {
context: async ({ req }) => ({
user: await authenticateRequest(req)
})
})
);
httpServer.listen(process.env.PORT || 4000);
Treat this as a configuration pattern, not a complete authentication system. The exact Apollo integration depends on your HTTP framework and package versions.
Set NODE_ENV=production in the deployment environment. Apollo Server uses production behavior in this mode, including disabling introspection by default. Apollo also provides separate landing page plugins for local development, production, and full disablement.
Use the Apollo security checklist to review authentication, authorization, query abuse, and sensitive data exposure.
Keep authorization inside resolvers
Authentication identifies the caller. Authorization decides what that caller can access.
Check authorization at the resolver or service layer, not only at the HTTP route. A user who can call viewer may not be allowed to request another user’s invoices by changing an ID.
Apply the same rule to nested fields. A protected top-level query can still expose private data through an overlooked relationship resolver.
Keep tokens, database passwords, signing keys, and third-party credentials out of logs. Mask authorization headers in request logging. Give each environment separate credentials and rotate them through the approved secrets system.
PROTECT THE GRAPHQL ENDPOINT
GraphQL allows clients to request different shapes and depths. A limit based only on requests per minute is not enough.
Restrict introspection and query shape
Public production introspection makes it easier for an unknown caller to map your schema. Disable it for unauthenticated production traffic unless your product requires a public developer schema.
Don’t treat introspection as your only security control. It doesn’t stop a user from calling a known field. Authorization, query limits, and data filtering still apply.
Apollo’s explanation of disabling GraphQL introspection in production covers the exposure created by returning schema details to unauthenticated clients.
Add controls for:
- Query depth
- Query complexity
- Maximum list and connection limits
- Request body size
- Resolver and upstream timeouts
- Alias and field repetition
- Expensive search and reporting operations
Persisted operations are useful when your clients are controlled. The server accepts registered query documents instead of arbitrary query text. This reduces the public query surface and makes traffic easier to audit.
Apply rate limits at multiple levels
Use an edge or gateway limit for IP addresses and a user-level limit after authentication. Add stricter limits to expensive operations such as exports, full-text search, and nested reports.
A request limit should account for query cost. Ten small profile queries aren’t equivalent to ten queries that load five nested collections.
The GraphQL.js production guide references schema-based rate limiting options. You can also enforce limits in your gateway, API middleware, or application service. Start with measured limits in staging, then watch rejected requests and database load after release.
Return a stable error for throttled requests. Include a retry hint only when your policy supports it. Don’t reveal internal counters, user identifiers, or infrastructure details.
MANAGE SCHEMA CHANGES BEFORE RELEASE
A schema is a contract between your server and its clients. A deployment can be technically healthy while breaking mobile apps, background jobs, or partner integrations.
Store schema definitions and resolver changes in version control. Run these checks in CI:
- Build the schema from a clean checkout.
- Run unit tests for resolvers and authorization.
- Run integration tests against a test database.
- Execute representative client queries.
- Check for breaking schema changes.
- Build and scan the production image.
- Deploy to staging.
- Run smoke tests against the staging endpoint.
Adding a field is usually safer than removing one. Deprecate old fields first. Track client usage before deletion. When changing a database column, use an expand-and-contract migration: add the new structure, support both versions, migrate data, then remove the old structure in a later release.
If you use Apollo GraphOS, publish schema changes through CI rather than manually from a laptop. The GraphOS schema publishing documentation describes publishing through the Rover CLI or Platform API.
Keep schema checks separate for staging and production. A schema that passes against staging clients may still break an older production application.
ADD OBSERVABILITY BEFORE TRAFFIC ARRIVES
You can’t operate a GraphQL API from HTTP status codes alone. A request can return 200 OK while the response contains GraphQL errors or a slow resolver has damaged the user experience.
Track these measurements:
- Request count by operation name
- GraphQL error count and error category
- Latency at the 50th, 95th, and 99th percentiles
- Resolver and database duration
- Timeout count
- Rate-limit responses
- Authentication failures
- Query depth and complexity
- CPU, memory, connection pool, and event-loop pressure
Use structured logs. Include a request ID, operation name, response status, duration, and deployment version. Don’t log full queries when they can contain sensitive arguments. Never log access tokens or personal data without a defined security need.
OpenTelemetry provides a standard starting point for Node.js traces, metrics, and logs. The OpenTelemetry Node.js guide explains the initial setup and instrumentation model.
Add health checks and graceful shutdown
Use a lightweight /healthz route for process health. Add a deeper readiness check if the platform needs to know whether the API can reach its database or required dependencies.
Don’t make a health route run an expensive GraphQL query. It should respond quickly and predictably.
Handle shutdown signals. Stop accepting new requests, allow active requests to finish within a deadline, close database pools, and then exit. Your platform can replace the old container without cutting off every in-flight request.
VALIDATE THE DEPLOYED ENDPOINT
Deployment is incomplete until the public endpoint passes functional and security checks.
Run basic checks against the real environment:
curl -fsS https://api.example.com/healthz
curl -fsS https://api.example.com/graphql
-H "content-type: application/json"
-d '{"query":"{ __typename }"}'
The health request should return a successful status. The GraphQL request should return valid JSON and the expected __typename value.
Then test the failure paths:
- Send an unauthenticated request to a protected field.
- Request an object belonging to another test user.
- Submit an invalid query.
- Send a request above the body-size limit.
- Run a query that exceeds the depth or complexity limit.
- Confirm introspection is blocked for public production traffic.
- Trigger a controlled upstream timeout.
- Confirm rate limiting returns the expected error.
- Check that logs contain no secret or token values.
Use separate test accounts and test data. Don’t create fake purchases, destructive records, or production side effects to validate a query.
Record the deployed image digest, schema version, migration version, configuration revision, and release timestamp. If the release fails, roll back the application image and schema-compatible changes together. A rollback that leaves the database at an incompatible version can create a second outage.
CONCLUSION
A production GraphQL API needs more than a working resolver tree. Build a repeatable container, configure production defaults, protect query execution, manage schema changes through review, and add telemetry before users depend on the service.
Start with a staging deployment that matches production settings. Validate health, authentication, authorization, rate limits, errors, introspection, and shutdown behavior. When you deploy GraphQL API code this way, the endpoint becomes a controlled service with measurable failure points and a clear recovery path.
