hiro/apollo-server
1
0
Fork 0
mirror of https://github.com/vale981/apollo-server synced 2025-03-05 17:51:40 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge branch 'master' into defer-support

Browse source
This commit is contained in:
clarencenpy 2018-08-07 10:44:46 -07:00
commit 0fc3d2a532
6 changed files with 165 additions and 104 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

69
docs/source/deployment/heroku.md
View file

@ -4,26 +4,44 @@ sidebar_title: Heroku
description: Deploying your GraphQL server to Heroku
---
Heroku is a common Platform as a Service that allows you to deploy your Apollo Server and have a functional GraphQL endpoint.
Heroku is a common Platform as a Service solution that allows users to deploy and have a functioning GraphQL endpoint running in a matter of minutes.
## Prerequisites
<h3 id="configure-heroku" title="Configure Heroku">1. Create and set up a new Heroku application</h3>
The following must be done before following this guide:
Log into the [Heroku dashboard](https://dashboard.heroku.com/apps). Then click “New” > “Create New App” in the top right. The name you choose will be used later in this tutorial as <HEROKU_APP_NAME>, so be sure to replace it in the later sections.
- Setup a [Heroku](https://heroku.com) account
- [Install the Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) if pushing to Heroku manually (see below)
<h2 id="configure-heroku" title="Configure Heroku">Set up a new Heroku application</h2>
Before deploying, a new application must be setup. To do this, log into the [Heroku dashboard](https://dashboard.heroku.com/apps). Then click `New > Create New App` in the top right. The name you choose will be referred to later as `<HEROKU_APP_NAME>`, so be sure to replace it in the later sections.
<div style="text-align:center">
![New App Screenshot](../images/deployment/heroku/new-app.png)
<br></br>
</div>
Name your app and hit “Create app”
Name your app and hit "Create app"
<div style="text-align:center">
![Create App Screenshot](../images/deployment/heroku/create-app.png)
<br></br>
</div>
<h3 id="deploy" title="Deploy with Heroku Push">2. Push project to Heroku</h3>
## Setting up the project
For Heroku, projects can be setup using any of the `apollo-server` HTTP variants (like express, hapi, etc).
The only special consideration that needs to be made is to allow heroku to choose the port that the server is deployed to. Otherwise, there may be errors, such as a request timeout.
To configure `apollo-server` to use a port defined by Heroku at runtime, the `listen` function in your setup file can be called with a port defined by the `PORT` environment variable:
```
server.listen({ port: process.env.PORT || 4000 }).then(({ url }) => {
console.log(`🚀 Server ready at ${url}`);
});
```
## Deploying the project
There are a couple of ways to push projects to Heroku. Automatically, with GitHub integration, or manually using Heroku push.
<h3 id="deploy" title="Deploy with Heroku Push">Deploying with Heroku push</h3>
Install the [Heroku Cli](https://devcenter.heroku.com/articles/heroku-cli), then inside of your project, run:
@ -33,34 +51,27 @@ $ heroku git:remote -a <HEROKU_APP_NAME>
$ git add .
$ git commit -am "make it better"
$ git push heroku master
$ git push heroku master # or your branch name
```
Send a query to your GraphQL service at your Heroku Application at `<HEROKU_APP_NAME>.herokuapp.com`
> Note: If you are using a project pushed to GitHub, you may want to setup automatic deployments from your repository, which you can do by following the steps in [this section](#github-deploy).
<h3>Automatically deploying with GitHub</h3>
<h3 id="env-vars" title="Environment variables">3. Configure environment variables</h3>
If the project is already pushed to GitHub, it may be easier to setup automatic deployments from the project's repository
On the Heroku dashboard, click on the name of the app that will be deployed from GitHub.
Then, on the app deatail page, there is a tab bar at the top, with a "Deploy" option. On that page, the deployment method can be chosen and setup to integrate with GitHub.
![github deployment instructons](../images/deployment/heroku/heroku-github-instructions.png)
<h2 id="env-vars" title="Environment variables"> Configuring environment variables</h2>
In order to enable the production mode of Apollo Server, you will need to set the `NODE_ENV` variable to production. To ensure you have visibility into your GraphQL performance in Apollo Server, you'll want to add the `ENGINE_API_KEY` environment variable to Heroku. For the API key, log into the [Engine UI](https://engine.apollographql.com) and navigate to your service or create a new one.
Then under the “Settings” tab, click “Reveal Config Vars". Next set `NODE_ENV` to `production` and copy your key from the [Engine UI](http://engine.apollographql.com/) as the value for `ENGINE_API_KEY`.
<div style="text-align:center">
![Add Engine Api Key Screenshot](../images/deployment/heroku/add-env-vars.png)
<br></br>
</div>
Send a query to your GraphQL service at your Heroku Application at `<HEROKU_APP_NAME>.herokuapp.com` and then check out the tracing data in the [Engine UI](http://engine.apollographql.com/).
> If you would like your GraphQL service to be exposed on a different port, you can also add a PORT environment variable.
<h3 id="github-deploy" title="Github Deploy">Deploying directly from GitHub</h3>
If you have your project published to github, you are able to setup Heroku to perform automatic deployments from branch. If you have pushed your project GitHub, you may select a branch in your repository that will trigger deploys.
<div style="text-align:center">
![Add Integration Screenshot](../images/deployment/heroku/add-integration.png)
<br></br>
</div>

148
docs/source/deployment/lambda.md
View file

@ -4,21 +4,37 @@ sidebar_title: Lambda
description: How to deploy Apollo Server with AWS Lambda
---
AWS Lambda is a service that lets you run code without provisioning or managing servers. You pay only for the compute time you consume-there is no charge when your code is not running.
AWS Lambda is a service that allows users to run code without provisioning or managing servers. Cost is based on the compute time that is consumed, and there is no charge when code is not running.
Learn how to integrate Apollo Server 2 with AWS Lambda. First, install the `apollo-server-lambda` package:
This guide explains how to setup Apollo Server 2 to run on AWS Lambda.
## Prerequisites
The following must be done before following this guide:
- Setup an AWS account
- [Install the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/installing.html)
- [Configure the AWS CLI with user credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)
- Install the serverless framework from NPM
- `npm install -g serverless`
---
## Setting up your project
Setting up a project to work with Lambda isn't that different from a typical NodeJS project.
First, install the `apollo-server-lambda` package:
```sh
npm install apollo-server-lambda graphql
```
## Deploying with AWS Serverless Application Model (SAM)
To deploy the AWS Lambda function, you must create a Cloudformation Template and a S3 bucket to store the artifact (zip of source code) and template. You'll use the [AWS Command Line Interface](https://aws.amazon.com/cli/).
#### 1. Write the API handlers
Next, set up the schema's type definitions and resolvers, and pass them to the `ApolloServer` constructor like normal. Here, `ApolloServer` must be imported from `apollo-server-lambda`. It's also important to note that this file must be named `graphql.js`, as the config example in a later step depends on the filename.
```js
// graphql.js
const { ApolloServer, gql } = require('apollo-server-lambda');
// Construct a schema, using GraphQL schema language
@ -40,66 +56,78 @@ const server = new ApolloServer({ typeDefs, resolvers });
exports.graphqlHandler = server.createHandler();
```
#### 2. Create an S3 bucket
Finally, **pay close attention to the last line**. This creates an export named `graphqlHandler` with a Lambda function handler.
The bucket name must be universally unique.
## Deploying with the Serverless Framework
```bash
aws s3 mb s3://<bucket name>
```
[Serverless](https://serverless.com) is a framework that makes deploying to services like AWS Lambda simpler.
#### 3. Create the Template
### Configuring the Serverless Framework
This will look for a file called `graphql.js` with the export `graphqlHandler`. It creates one API endpoints:
Serverless uses a config file named `serverless.yml` to determine what service to deploy to and where the handlers are.
* `/graphql` (GET and POST)
In a file called `template.yaml`:
```yaml
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Resources:
GraphQL:
Type: AWS::Serverless::Function
Properties:
Handler: graphql.graphqlHandler
Runtime: nodejs8.10
Events:
GetRequest:
Type: Api
Properties:
Path: /graphql
Method: get
PostRequest:
Type: Api
Properties:
Path: /graphql
Method: post
```
#### 4. Package source code and dependencies
Read and transform the template, created in the previous step. Package and upload the artifact to the S3 bucket and generate another template for the deployment.
```sh
aws cloudformation package \
--template-file template.yaml \
--output-template-file serverless-output.yaml \
--s3-bucket <bucket-name>
```
#### 5. Deploy the API
Create the Lambda Function and API Gateway for GraphQL. In the example below, `prod` stands for production. However, you can use any name to represent it.
For the sake of this example, the following file can just be copied and pasted into the root of your project.
```
aws cloudformation deploy \
--template-file serverless-output.yaml \
--stack-name prod \
--capabilities CAPABILITY_IAM
# serverless.yml
service: apollo-lambda
provider:
name: aws
runtime: nodejs6.10
functions:
graphql:
# this is formatted as <FILENAME>.<HANDLER>
handler: graphql.graphqlHandler
events:
- http:
path: graphql
method: post
cors: true
```
### Running the Serverless Framework
After configuring the Serverless Framework, all you have to do to deploy is run `serverless deploy`
If successful, `serverless` should output something similar to this example:
```
> serverless deploy
Serverless: Packaging service...
Serverless: Excluding development dependencies...
Serverless: Uploading CloudFormation file to S3...
Serverless: Uploading artifacts...
Serverless: Uploading service .zip file to S3 (27.07 MB)...
Serverless: Validating template...
Serverless: Updating Stack...
Serverless: Checking Stack update progress...
..............
Serverless: Stack update finished...
Service Information
service: apollo-lambda
stage: dev
region: us-east-1
stack: apollo-lambda-dev
api keys:
None
endpoints:
POST - https://ujt89xxyn3.execute-api.us-east-1.amazonaws.com/dev/graphql
functions:
graphql: apollo-lambda-dev-graphql
```
#### What does `serverless` do?
First, it builds the functions, zips up the artifacts, and uploads the artifacts to a new S3 bucket. Then, it creates a Lambda function with those artifacts, and if successful, outputs the HTTP endpoint URLs to the console.
### Managing the resulting services
The resulting S3 buckets and Lambda functions can be viewed and managed after logging in to the [AWS Console](https://console.aws.amazon.com).
- To find the created S3 bucket, search the listed services for S3. For this example, the bucket created by Serverless was named `apollo-lambda-dev-serverlessdeploymentbucket-1s10e00wvoe5f`
- To find the created Lambda function, search the listed services for `Lambda`. If the list of Lambda functions is empty, or missing the newly created function, double check the region at the top right of the screen. The default region for Serverless deployments is `us-east-1` (N. Virginia)
## Getting request info
To read information about the current request from the API Gateway event `(HTTP headers, HTTP method, body, path, ...)` or the current Lambda Context `(Function Name, Function Version, awsRequestId, time remaning, ...)`, use the options function. This way, they can be passed to your schema resolvers via the context option.
@ -129,13 +157,13 @@ const server = new ApolloServer({
functionName: context.functionName,
event,
context,
})
}),
});
exports.graphqlHandler = server.createHandler();
```
## Modifying the Lambda Response (Enable CORS)
## Modifying the Lambda response (Enable CORS)
To enable CORS, the response HTTP headers need to be modified. To accomplish this, use the `cors` options.

48
docs/source/deployment/now.md
View file

@ -4,11 +4,16 @@ sidebar_title: Now
description: Deploying your GraphQL server to Zeit Now
---
Now is a service by Zeit that allows the deployment of an instance of Apollo Server, which provides a functional GraphQL endpoint.
[Now](https://zeit.co/now) is a service by Zeit that allows the deployment of an instance of Apollo Server, quickly providing a functional GraphQL endpoint.
## Node.js Deployment
## Prerequisites
Deployment to Now for Node.js apps simply requires a `package.json` file to be present in your app directory.
- A [Now](https://zeit.co/now) account
- The [Now CLI](https://zeit.co/download#now-cli) (unless using [automatic GitHub deployments](#automatic-github-deploys))
## Setting up the project
Deployment to [Now](https://zeit.co/now) for Node.js apps requires a `package.json` file to be present in the app's root directory.
```js
{
@ -25,33 +30,50 @@ Deployment to Now for Node.js apps simply requires a `package.json` file to be p
}
```
### Deploy server to Now
[Now](https://zeit.co/now) looks for a `start` script to start the app. As long as that is in the `package.json`, the app should be able to start up.
Install the [now CLI](https://zeit.co/download#now-cli), then visit your server directory and run the `now` command:
## Deploying with Now
[Now](https://zeit.co/now) offers multiple options for deploying projects.
### Local Projects
If the [Now](https://zeit.co/now) CLI is installed, then running the `now` command from the root directory of the project should deploy the project.
```sh
$ now
```
The `now` command immediately deploys your server to the cloud and returns the hosted project link. Send a query to your GraphQL server on `now` at `<NOW_APP_NAME>.now.sh`.
The `now` command immediately deploys a server to the cloud and returns the hosted project link. After finishing, it should be possible to send a query to the GraphQL schema on `now` at `<NOW_APP_NAME>.now.sh/graphql`.
### Deploying directly from GitHub
### Manual GitHub deployment
If you have your GraphQL server published to GitHub, Now provides the ability to deploy straight from GitHub to the cloud.
If a GraphQL server project is publically available on GitHub, [Now](https://zeit.co/now) provides the ability to deploy straight from GitHub by calling the `now` command with the user/organization name and repository name in the format `user/repository-name`.
Assuming you'd like to deploy an instance of [apollo](https://github.com/apollographql)'s [graphql-server-example](https://github.com/apollographql/graphql-server-example), this is what you'll do:
For example, to deploy Apollo's [graphql-server-example](https://github.com/apollographql/graphql-server-example), the command would be:
```sh
$ now apollographql/graphql-server-example
```
The `now` command deploys right away and gets the server up and running on the cloud. Furthermore, running the following command will automatically start delivering reports to Apollo Engine.
The `now` command deploys right away and attempts to start the server. This specific example would fail though, due to missing environment variables. They can be added by following the [section](#env-variables) on environment variables.
<h3 id="automatic-github-deploys">Automatic GitHub deployment</h3>
[Now](https://zeit.co/now) supports automatic deployment from GitHub on pull requests.
To set up automatic deployment, visit [https://zeit.co/github](https://zeit.co/github) and click on the "Setup Now" button.
After signing in with GitHub, the [Now](https://zeit.co/now) GitHub app can be added to any account or organization. Once installed, it's possible to choose which repositories that [Now](https://zeit.co/now) can run on, allowing new deployments on Pull Requests.
![now permissions setup](../images/deployment/zeit/now-github-permissions.png)
<h2 id="env-variables">Setting environment variables</h2>
The `graphql-server-example` project requires environment variables to enable reporting to Apollo Engine. To deploy to Now with environment variables, the `-e` flag can be used followed by the variables like so:
```sh
$ now -e ENGINE_API_KEY=xxxxxxxxx apollographql/graphql-server-example
```
<div style="text-align:center">
![Deployed GraphQL Server](../images/deployment/zeit/zeit-apollo-server.png)
<br></br>
</div>

4
docs/source/features/data-sources.md
View file

@ -9,10 +9,10 @@ Data sources are classes that encapsulate fetching data from a particular servic
A `RESTDataSource` is responsible for fetching data from a given REST API.
To get started, install the release candidate of the REST data source:
To get started, install the REST data source package:
```bash
npm install apollo-datasource-rest@rc
npm install apollo-datasource-rest
```
To define a data source, extend the `RESTDataSource` class and implement the data fetching methods that your resolvers require. Your implementation of these methods can call on convenience methods built into the `RESTDataSource` class to perform HTTP requests, while making it easy to build up query parameters, parse JSON results, and handle errors.

BIN
docs/source/images/deployment/heroku/heroku-github-instructions.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 434 KiB

BIN
docs/source/images/deployment/zeit/now-github-permissions.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 253 KiB