Self-host Graph Artifacts

Mirror graph artifacts to a local registry, or push your own self-hosted artifacts

Requires ≥ Router v2.7.0

To run graph artifacts independently of Apollo's hosted registry, use one of these methods:

  • Mirror to a local OCI registry: Proxy and cache Apollo's artifacts through your own registry infrastructure. Doing that is useful for air-gapped or restricted network environments.

  • Push self-hosted artifacts: Compose a supergraph schema locally with Rover and push it to any OCI-compliant registry you control.

Mirror to a local OCI registry

Configure your own OCI-compatible artifact registry to mirror graph artifacts from Apollo. By setting up a remote repository, you can proxy and cache Apollo artifacts through your own registry infrastructure.

Running a local OCI registry provides multiple benefits:

  • Remove dependence on Apollo for deployments: Deploy without requiring connectivity to Apollo's registry.

  • Enhance security and compliance: Keep artifacts within your own infrastructure.

  • Reduce network latency: Serve artifacts from a registry closer to your routers.

  • Maintain complete control: Make sure you have full ownership of artifact storage and lifecycle.

Prerequisites

  • An Apollo account with a valid graph API key

  • Administrative access to your artifact registry (for example, JFrog Artifactory)

  • The ORAS CLI (optional, used for testing)

  • Your current Apollo artifact reference (for example, artifact.api.apollographql.com/your-graph-id:tag)

General configuration

Configure your OCI-compatible registry with these parameters:

ParameterValue
Remote URLhttps://artifact.api.apollographql.com/
Usernameapollo
PasswordYour Apollo graph API key

Set up JFrog Artifactory

Configure JFrog Artifactory as your OCI artifact mirror:

  1. Go to Administration > Repositories, then select Create a Repository > Remote.

  2. Select OCI as the package type.

  3. Enter a repository key (for example, apollo-artifacts) and configure these settings:

    • URL: https://artifact.api.apollographql.com/

    • User Name: apollo

    • Password / Access Token: Your Apollo graph API key

  4. Use these advanced settings to ensure proper artifact retrieval:

    • Clear the Block Mismatching MIME Types checkbox

    • Select Bypass HEAD Requests

    • Select Disable URL Normalization.

Configure the router

After you've configured your remote repository, update the APOLLO_GRAPH_ARTIFACT_REFERENCE environment variable to point to your local registry. Replace the Apollo artifact URL with your registry URL and repository, but keep the graph identifier and tag.

Bash
1# Original reference:
2APOLLO_GRAPH_ARTIFACT_REFERENCE="artifact.api.apollographql.com/your-graph-id:your-tag"
3
4# Updated reference pointing to your local registry:
5APOLLO_GRAPH_ARTIFACT_REFERENCE="your-registry.com/remote-repository/your-graph-id:your-tag"

Verify the configuration

To confirm the configuration has been set up correctly, sign in to your registry using the ORAS client and pull an artifact:

Bash
1# Log in to your registry
2oras login your-artifactory-instance.jfrog.io
3
4# Pull an artifact from your mirrored repository
5oras pull your-artifactory-instance.jfrog.io/apollo-artifacts/your-graph-id:your-tag

A successful pull confirms that your remote repository is correctly configured and can fetch artifacts from Apollo GraphQL.

Cache settings

When you use a mirrored repository, set a short cache TTL to ensure timely updates and reduce the delay between a new artifact version becoming available in Apollo and your local registry.

Push self-hosted artifacts

A supergraph schema can be composed locally with Rover and pushed to an OCI registry you control—for example, a private registry or AWS ECR. Apollo Router can then run using that artifact.

Schema layer media type

Apollo Router expects the schema layer to use the media type application/apollo.schema. When you push with ORAS, specify the media type explicitly using the ORAS file syntax local_file_path:media_type:

Bash
1oras push your-registry.com/supergraph-schema:latest \
2  path/to/supergraph-schema.graphql:application/apollo.schema

Use a digest reference

APOLLO_GRAPH_ARTIFACT_REFERENCE must be a digest reference (@sha256:...), not a tag. Tag references like your-registry.com/supergraph-schema:latest don't work. After pushing, resolve the digest and use the full reference:

Bash
1oras discover your-registry.com/supergraph-schema:latest
2# Output: your-registry.com/supergraph-schema@sha256:e5c8efeb176643feba5ff32cbb8e8d15ffc6323dadaa748b902fa68890792607

Set APOLLO_GRAPH_ARTIFACT_REFERENCE to that full registry/repo@sha256:digest string.

Set APOLLO_KEY

When the schema source is an OCI artifact, APOLLO_KEY must be set (any valid graph API key). Apollo Router doesn't use the OCI reference without it.

Run Apollo Router

Set APOLLO_GRAPH_REF, APOLLO_KEY, and APOLLO_GRAPH_ARTIFACT_REFERENCE (using your digest from oras discover), then start Apollo Router:

Bash
1APOLLO_GRAPH_REF="your_graph_id@variant_name" \
2APOLLO_KEY="your_apollo_key" \
3APOLLO_GRAPH_ARTIFACT_REFERENCE="your-registry.com/your-repo@sha256:digest" \
4./router