From 3a521cb9e309b1c5509e53ef8ae11f0cc2756d2c Mon Sep 17 00:00:00 2001 From: Victoria Date: Fri, 21 Feb 2020 13:57:50 -0600 Subject: [PATCH] Add Cloudflare Workers documentation --- docs/docs/deploying-to-cloudflare-workers.md | 124 +++++++++++++++++++ docs/docs/preparing-for-deployment.md | 1 + docs/docs/recipes.md | 1 + docs/docs/recipes/deploying-your-site.md | 24 ++++ www/src/data/sidebars/doc-links.yaml | 3 + 5 files changed, 153 insertions(+) create mode 100644 docs/docs/deploying-to-cloudflare-workers.md diff --git a/docs/docs/deploying-to-cloudflare-workers.md b/docs/docs/deploying-to-cloudflare-workers.md new file mode 100644 index 0000000000000..b0a17bbd62724 --- /dev/null +++ b/docs/docs/deploying-to-cloudflare-workers.md @@ -0,0 +1,124 @@ +--- +title: Deploying to Cloudflare Workers +--- + +[Cloudflare Workers](https://workers.cloudflare.com/) is a serverless platform for creating entirely new applications or augmenting existing ones without configuring or maintaining infrastructure. With [Workers Sites](https://developers.cloudflare.com/workers/sites/start-from-existing/) you can deploy any static site including your Gatsby projects to a domain on Cloudflare or for free with on your [workers.dev](workers.dev) subdomain. + +To enable the KV store required to serve the Gatsby files, you'll need the [Workers Unlimited plan](https://developers.cloudflare.com/workers/about/pricing/) for \$5/month. + +This guide will get you started in a few steps: + +1. Installing wrangler CLI + +Workers Sites requires [wrangler](https://developers.cloudflare.com/workers/tooling/wrangler/). The more straight forward way to install wrangler is with [npm](https://www.npmjs.com/), run the following command: + +```shell +npm i -g @cloudflare/wrangler +``` + +2. Initialize the Project + +To create the Worker code that will serve your Gatsby files, from the root of your Gatsby project run: + +``` +wrangler init --site +``` + +You'll notice your project structure should now look something like: + +```diff ++ ├── workers-site ++ └── wrangler.toml ++ │   ├── index.js ++ │   ├── package-lock.json ++ │   └── package.json + ├── src + │   ├── components + │   ├── images + │   └── pages + ├── gatsby-config.js + ├── package.json +``` + +3. Configure + +To authenticate into your Cloudflare account run: + +``` +wrangler config +``` + +Follow the [Quick Start](https://developers.cloudflare.com/workers/quickstart/#configure) for steps on gathering the correct account ID and API token to link wrangler to your Cloudflare account. + +If you don't already have a workers.dev domain run: + +``` +wrangler subdomain +``` + +Then, add your account ID to the `wrangler.toml` file, and set `bucket` to `"./public"`, which is where Gatsby's built files are output by default: + +``` +name = "gatsby-project" +type = "webpack" +account_id = "abcd..." +workers_dev = true + +[site] +bucket = "./public" +entry-point = "workers-site" +``` + +This deploys to your workers.dev subdomain. For a custom domain see [Quick Start](https://developers.cloudflare.com/workers/quickstart/#publish-to-your-domain). + +4. Deploy + +You can deploy your application by running the following command in the root of the project directory: + +```shell +wrangler publish +``` + +Now your site is available at gatsby-project.subdomain.workers.dev! + +5. CI with Github Actions + +Use wrangler's Github action [plugin](https://github.com/cloudflare/wrangler-action) to automatically deploy to Workers every time you push to master. + +Once Github Actions is enabled on your repo, add a file to your project's root called `.github/workflows/main.yml` with the contents: + +``` +name: Deploy production site + +on: + push: + branches: + - master + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - name: Navigate to repo + run: cd $GITHUB_WORKSPACE + - uses: actions/setup-node@v1 + with: + node-version: '10.x' + - name: Install deps + run: npm install + - name: Build docs + run: npm run build + - name: Publish + uses: cloudflare/wrangler-action@1.1.0 + with: + apiToken: ${{ secrets.CF_API_TOKEN }} + environment: "production" +``` + +Set up `CF_API_TOKEN` in Github secrets with appropriate values from [Quick Start](https://developers.cloudflare.com/workers/quickstart/#configure). + +## References: + +- [Quickstart for Workers Sites](https://developers.cloudflare.com/workers/sites/start-from-existing/) +- [Github Action wrangler plugin](https://github.com/cloudflare/wrangler-action) diff --git a/docs/docs/preparing-for-deployment.md b/docs/docs/preparing-for-deployment.md index cd83888e776a6..3319c4f4f35c6 100644 --- a/docs/docs/preparing-for-deployment.md +++ b/docs/docs/preparing-for-deployment.md @@ -47,6 +47,7 @@ If you have a server from one of the following providers, you should read the in - [Aerobatic](/docs/deploying-to-aerobatic) - [Heroku](/docs/deploying-to-heroku) - [ZEIT Now](/docs/deploying-to-zeit-now) +- [Cloudflare Workers](/docs/deploying-to-cloudflare-workers) - [GitLab Pages](/docs/deploying-to-gitlab-pages) - [Netlify](/docs/deploying-to-netlify) - [Render](/docs/deploying-to-render) diff --git a/docs/docs/recipes.md b/docs/docs/recipes.md index 516f6f1e3b2eb..a74bb97a7e608 100644 --- a/docs/docs/recipes.md +++ b/docs/docs/recipes.md @@ -116,3 +116,4 @@ Showtime. Once you are happy with your site, you are ready to go live with it! - [Preparing for deployment](/docs/recipes/deploying-your-site#preparing-for-deployment) - [Deploying to Netlify](/docs/recipes/deploying-your-site#deploying-to-netlify) - [Deploying to ZEIT Now](/docs/recipes/deploying-your-site#deploying-to-zeit-now) +- [Deploying to Cloudflare Workers](/docs/deploying-your-site#deploying-to-cloudflare-workers/) diff --git a/docs/docs/recipes/deploying-your-site.md b/docs/docs/recipes/deploying-your-site.md index 25d6693493f90..a64bd74480fea 100644 --- a/docs/docs/recipes/deploying-your-site.md +++ b/docs/docs/recipes/deploying-your-site.md @@ -82,6 +82,30 @@ Use [`netlify-cli`](https://www.netlify.com/docs/cli/) to deploy your Gatsby app - [Hosting on Netlify](/docs/hosting-on-netlify) - [gatsby-plugin-netlify](/packages/gatsby-plugin-netlify) +## Deploying to Cloudflare Workers + +Use [`wrangler`](https://developers.cloudflare.com/workers/tooling/wrangler/) to deploy your Gatsby application globally without leaving the command-line interface. + +### Prerequisites + +- A [Gatsby site](/docs/quick-start) set up with Gatsby's CLI +- [wrangler](https://developers.cloudflare.com/workers/tooling/wrangler/install/) installed globally (`npm i -g @cloudflare/wrangler`) + +### Directions + +1. Build your Gatsby application using `gatsby build` +2. Run `wrangler config` where you'll be prompted for your [Cloudflare API token](https://developers.cloudflare.com/workers/quickstart/#api-token) +3. Run `wrangler init --site` +4. Configure `wrangler.toml`. First add [account ID](https://developers.cloudflare.com/workers/quickstart/#account-id-and-zone-id) field and then either + 1. A free workers.dev domain by setting `workers_dev = true` + 2. A custom domain on Cloudflare by setting `workers_dev = false`, `zone_id = "abdc..` and `route = customdomain.com/*` +5. In `wrangler.toml` set `bucket = "./public"` +6. Run `wrangler publish` and your site will be deployed in seconds! + +### Additional resources + +- [Hosting on Cloudflare](/docs/deploying-to-cloudflare-workers) + ## Deploying to ZEIT Now Use [Now CLI](https://zeit.co/download) to deploy your Gatsby application without leaving the command-line interface. diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml index 7a134160bf441..90134d84c2987 100644 --- a/www/src/data/sidebars/doc-links.yaml +++ b/www/src/data/sidebars/doc-links.yaml @@ -76,6 +76,9 @@ - title: Deploying to ZEIT Now link: /docs/deploying-to-zeit-now/ breadcrumbTitle: ZEIT Now + - title: Deploying to Cloudflare Workers + link: /docs/deploying-to-cloudflare-workers/ + breadcrumbTitle: Cloudflare Workers - title: Deploying to GitLab Pages link: /docs/deploying-to-gitlab-pages/ breadcrumbTitle: GitLab Pages