.graphcoolrc (Targets & Clusters)

Last updated a day ago Edit this page


When using Graphcool, you can configure different targets to which you can deploy your services.

A target is a deployed instance of a Graphcool service. It is composed of two major components:

  • A cluster that determines the infrastructure and runtime environment for the service. This could be a locally running Graphcool Docker cluster or a shared cluster from the Graphcool Backend-as-a-Service.
  • A service ID that's generated by Graphcool when the target is created.

Targets can be used to separate different environments (like dev, staging or prod) for your service and are managed through the .graphcoolrc files.

All your targets and clusters are managed through .graphcoolrc files. There are two versions of .graphcoolrc.

#Global vs Local

  • The global version of .graphcoolrc that's stored in your home directory. This is used for global Graphcool configurations, such as cluster definitions or storing your platform token.
  • Several local versions of .graphcoolrc in your service directories. These are used to specify and manage targets for the corresponding service.

.graphcoolrc is written in YAML.

#Managing clusters in the global .graphcoolrc

The global .graphcoolrc lists a number of clusters that you can target with your deployments.

A cluster can be either:

  • A shared cluster hosted on the Graphcool Backend-as-a-Service. There are of these clusters available, one for each region:

    • shared-eu-west-1
    • shared-us-west-2
    • shared-ap-northeast-1
  • A Docker container that's running the required environment for Graphool services. In this case, it needs to have the following properties:

    • host: The URL of the Docker container.
    • clusterSecret: Secret to authenticate against the deployed Graphcool instance.

Here's an example for what the global .graphcoolrc might look like, when two clusters are configured:

  # The `default` cluster is `shared-eu-west-1` from the Graphcool BaaS
  default: shared-eu-west-1
  # The `local` cluster is a Docker container providing 
    host: 'http://localhost:60001'
    clusterSecret: >-
platformToken: >-

#Managing targets in a local .graphcoolrc

A target effectively is a deployed instance of a Graphcool service.

Most of the CLI commands accept the --target (short: -t) option to specify the target against which the command will run, for example:

graphcool-framework deploy --target prod

Targets are managed through local .graphcool-files. Here is an example of what a local .graphcoolrc for a specific service might look like:

  default: dev
  dev: shared-us-west-2/cj8n7vc0101ya01424ihgryke
  prod: shared-us-west-2/cj8n7um5800ox0167tzrqj5r9

If the --target option is not specified for a CLI command, the command will run against the default target from .graphcoolrc.

#Important notes

The CLI actually doesn't explicitly distinguish the local and global versions of .graphcoolrc. When a command is invoked, the CLI will first load the global .graphcoolrc and then load the local .graphcoolrc for the specific service. Note that any name clashes will be overridden in favor of the local .graphcoolrc.

So, it's potentially possible to specify targets in the global .graphcoolrc or clusters in the local .graphcoolrc. This might be helpful when configuring a CI setup for example, where you don't want to specficially access the home directory (which contains the global .graphcoolrc) of the CI environment.

Was this page helpful?