Skip to content

Commit 661d959

Browse files
committed
Restrcture production section:
1 parent 5ef5301 commit 661d959

File tree

1 file changed

+28
-72
lines changed

1 file changed

+28
-72
lines changed

docs/source/tutorial/production.md

Lines changed: 28 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -1,105 +1,61 @@
11
---
22
title: "4. Run your graph in production"
3-
description: Start here for the Apollo fullstack tutorial
3+
description: Learn about deployment and essential developer tooling
44
---
55

6-
<h2 id="deploy">Deploy your graph API</h2>
7-
8-
There are several services you can deploy your graph API to such as Heroku, Amazon Lambda, Netlify and Zeit's Now. We'll deploy our graph API to Zeit's **Now**. Now is a service by Zeit that allows the deployment of an instance of Apollo Server, quickly providing a functional GraphQL endpoint.
6+
Great job for making it this far! We've already learned how to build a graph API with Apollo, connect it to REST and SQL data sources, and send GraphQL queries. Now that we've completed building our graph, it's finally time to deploy it! 🎉
97

10-
You need the following before deployment:
8+
An Apollo graph API can be deployed to any cloud service, such as Heroku, AWS Lambda, or Netlify. In this tutorial, we'll deploy our graph API to [Zeit Now](https://zeit.co/now). You will need to create a [Now account](https://zeit.co/now) in order to follow these steps. If you haven't already created an [Apollo Engine](https://engine.apollographql.com/) account, you will need to sign up for one.
119

12-
* A [Now](https://zeit.co/now) account.
13-
* The [Now CLI](https://zeit.co/download#now-cli).
10+
<h2 id="engine">Publish your schema to Engine</h2>
1411

15-
Now looks for a `start` script in the `package.json` file to start the app. Once the script is present, Now will be able to start the app.
12+
Before we deploy your app, we need to publish our schema to the Apollo Engine cloud service in order to power developer tooling like VSCode and keep track of schema changes. Just like npm is a registry for JavaScript packages, Apollo Engine contains a schema registry that makes it simple to pull the most recent schema from the cloud.
1613

17-
Go ahead and run the `now` command from the root directory of the app to deploy our app to Now.
14+
In a production application, you should set up this publishing script as part of your CI workflow. For now, we will run a script in our terminal that uses the Apollo CLI to publish our schema to Engine.
1815

19-
```bash
20-
$ now
21-
```
16+
<h3 id="api-key">Get an Engine API key</h3>
2217

23-
The `now` command immediately deploys our graph API to the cloud and returns the hosted URL. The returned URL comes in this format: `<NOW_APP_NAME>.now.sh`.
18+
First, we need an Apollo Engine API key. Navigate to [Apollo Engine](https://engine.apollographql.com/), login, and click on New Service at the top. The prompt will instruct you to name your service. When you're finished, click Create Service. You'll see a key appear prefixed by `service:`. Copy that key so we can save it as an environment variable.
2419

25-
You can now query the graph service at `<NOW_APP_NAME>.now.sh/graphql`.
20+
Let's save our key as an environment variable. It's important to make sure we don't check our Engine API key into version control. Go ahead and make a copy of the `.env.example` file located in `server/` and call it `.env`. Add your Engine API key that you copied from the previous step to the file:
2621

27-
**Note:** Now also supports direct deployment from a GitHub repository. If your graph API is publicly available on GitHub, you can deploy it via the `now` command like so:
28-
29-
```bash
30-
now <github-username>/<repository-name>
3122
```
32-
33-
<h2 id="publish-schema">Publish your schema to Engine</h2>
34-
35-
Safely evolving your schema overtime requires a lot of developer efforts in ensuring that clients consuming your API do not break as a result of schema changes. The Apollo platform provides the ability to publish your schema to Engine via the [Apollo CLI](https://npm.im/apollo).
36-
37-
[Apollo Engine](https://engine.apollographql.com), provides deep insights into your graph layer that enables you to understand, optimize, and control your graph service in production with confidence.
38-
39-
Once we publish our schema to Apollo Engine, it becomes the basis for comparison for validating future schemas and avoiding breaking changes. Therefore, a schema should be re-published to Apollo Engine each time a new schema is deployed.
40-
41-
Go ahead and install the `apollo` CLI via npm:
42-
43-
```bash
44-
npm install --global apollo
23+
ENGINE_API_KEY=service:your-key-here
4524
```
4625

47-
To publish our schema to Apollo Engine, we need an API key.
26+
Our key is now stored under the environment variable `ENGINE_API_KEY`.
4827

49-
An API key can be obtained from a graph service’s _Settings_ menu within the [Apollo Engine dashboard](https://engine.apollographql.com).
28+
<h3 id="publish">Check and publish with the Apollo CLI</h3>
5029

51-
Now start your GraphQL server and run the command below:
30+
It's time to publish our schema to Engine! First, start your server in one terminal window by running `npm start`. In another terminal window, run:
5231

5332
```bash
54-
apollo schema:publish --key="<API_KEY>" --endpoint="https://<now_app_name>.now.sh/graphql"
33+
npx apollo schema:check && npx apollo schema:publish
5534
```
5635

57-
The `--endpoint` flag should be set to the URL of a running GraphQL server.
36+
This command checks your schema to ensure there are no breaking changes and publishes your schema to the Apollo registry. Once your schema is uploaded, you should be able to see your schema in the [Apollo Engine](https://engine.apollographql.com/) explorer. In future steps, we will pull down our schema from Engine in order to power the Apollo VSCode extension.
5837

59-
Every time the schema is updated, run the `apollo schema:publish` command so that Apollo Engine can provide a history of schema changes. This allows everyone on your team to know when new types and fields are added or removed. Apollo Engine also provides a reference to the commits that introduced changes to the schema.
38+
<h3 id="benefits">What are the benefits of Engine?</h3>
6039

61-
To check the difference between the current schema and a newly published schema version, you can run the command below:
40+
Publishing your schema to Apollo Engine unlocks many features necessary for running a graph API in production. Some of these features include:
6241

63-
```bash
64-
apollo schema:check --key="<API_KEY>" --endpoint="https://<now_app_name>.now.sh/graphql"
65-
```
66-
67-
Apollo Engine identifies three categories of changes and report them to the developer on the command line or within a GitHub pull-request:
68-
69-
* **Failure:** Either the schema is invalid or the changes will break current clients.
70-
* **Warning:** There are potential problems that may come from this change, but no clients are immediately impacted.
71-
* **Notice:** This change is safe and will not break current clients.
72-
73-
<h2 id="monitoring">Monitor your graph's performance</h2>
74-
75-
You need a bird's-eye view of your graph's API. Understanding how your schema fields, and queries operates within your graph service opens you to a whole new world of effective optimization and scaling!
42+
* **Schema explorer:** With Engine's powerful schema registry, you can quickly explore all the types and fields in your schema with usage statistics on each field. This metric makes you understand the cost of a field. How expensive is a field? Is a certain field in so much demand?
43+
* **Schema history:** Apollo Engine’s schema history allows developers to confidently iterate a graph's schema by validating the new schema against field-level usage data from the previous schema. This empowers developers to avoid breaking changes by providing insights into which clients will be broken by a new schema.
44+
* **Performance analytics:** Fine-grained insights into every field, resolvers and operations of your graph's execution
45+
* **Performance alerts:** You can configure notifications to be sent to various channels like Slack, and PagerDuty. Apollo Engine can be set to send alerts when a request rate, duration or error rate exceeds a certain threshold.
7646

77-
In order to get access to your graph's performance metrics, hook up Apollo Server with Engine. Connect to Engine by passing the API key to the Apollo Server constructor:
47+
We also want to be transparent that the features we just described, such as field metrics, performance alerts, and validating schema changes against recent operations, are only available on a paid plan. Individual developers just getting started with GraphQL probably don't need these features, but they become incredibly valuable as you're working on a team. Additionally, layering these paid features on top of our free developer tools like Apollo VSCode makes them more intelligent over time.
7848

79-
_src/index.js_
49+
We're committed to helping you succeed building and running an Apollo graph API. This is why features such as publishing and downloading schemas from the registry, our open source offerings like Apollo Client and Apollo Server, and certain developer tools like Apollo VSCode and Apollo DevTools will always be free forever.
8050

81-
```js
82-
// Set up Apollo Server
83-
const server = new ApolloServer({
84-
...
85-
...
86-
engine: process.env.ENGINE_API_KEY ? { apiKey: process.env.ENGINE_API_KEY } : undefined,
87-
});
88-
```
51+
<h2 id="deploy">Deploy your graph API</h2>
8952

90-
Set the `ENGINE_API_KEY` environment variable via the command line:
53+
To deploy our app to Now, run the `now` command from the `server` directory of the app. The command may prompt you to login if you haven't already.
9154

9255
```bash
93-
$ ENGINE_API_KEY=YOUR_API_KEY npm start
56+
$ npx now
9457
```
9558

96-
Once this is done, run a query in GraphQL Playground, and log in to your Engine account to monitor the graph's performance.
97-
98-
Apollo Engine provides all of the following features highlighted below:
99-
100-
* **Schema Explorer:** With Engine's powerful schema registry, you can quickly explore all the types and fields in your schema with usage statistics on each field. This metric makes you understand the cost of a field. How expensive is a field? Is a certain field in so much demand?
101-
* **Schema history:** Apollo Engine’s schema history allows developers to confidently iterate a graph's schema by validating the new schema against field-level usage data from the previous schema. This empowers developers to avoid breaking changes by providing insights into which clients will be broken by a new schema.
102-
* **Performance Analytics:** Fine-grained insights into every field, resolvers and operations of your graph's execution.
103-
* **Performance alerts:** You can configure notifications to be sent to various channels like Slack, and PagerDuty. Apollo Engine can be set to send alerts when a request rate, duration or error rate exceeds a certain threshold. You can effectively monitor everything going on in your graph's service.
59+
The `now` command immediately deploys our graph API to the cloud and returns the hosted URL. Make sure you either copy the URL or run `npx now ls` in your terminal to retrieve the URL, since we'll need it in the following section when we build our client.
10460

105-
The [Engine](https://www.apollographql.com/docs/engine/) guide provides detailed instructions on how Apollo Engine works and the setup for any type for performance or usage analytics.
61+
Congrats on deploying your first Apollo graph API! 🚀 Let's move on to the second half of the tutorial where we connect the API we just built to a React app.

0 commit comments

Comments
 (0)