Skip to content

Latest commit

 

History

History
151 lines (103 loc) · 7.21 KB

readme.md

File metadata and controls

151 lines (103 loc) · 7.21 KB
Raw

A Node.js library for deploying websites and Node.js services to Google Cloud Platform (GCP) using Google App Engine

build status badge npm version badge

Features

This library can be used to automate the deployment of static websites and Node.js services to GCP with minimal configuration and just a handful of conventions. Its features include:

  • Custom domains
  • https
  • Version management
  • Low cost
  • High availability

Install

npm install @carnesen/google-cloud

The package includes runtime JavaScript files suitable for Node.js >=8 as well as the corresponding TypeScript type declarations. There are also a number of one-time manual setup steps that you'll need to do if you haven't already:

Create a project

Sign in to the Google Cloud console and create a new "project" and note its "project ID", which you'll need later.

Purchase a domain name

Use Google Domains or any other registrar to purchase a top-level domain, e.g. "example.com". Your sites and services will be served at the apex "example.com" and on subdomains "www.example.com".

Create a Cloud DNS zone

In the Google Cloud console, navigate to "Network Services" > "Cloud DNS". Follow the prompts to create a new public "zone". Note its "zone name", which you'll need later.

Delegate name resolution to Google Cloud

In the Google Cloud console, navigate to "Network Services" > "Cloud DNS". Click on the "Registrar Setup" link in the upper right-hand corner. This reveals the "NS" (name server) records for your managed zone. Copy these NS records over to your domain registrar. Details differ by provider. Here's how to do it with Google Domains.

Install the Google Cloud SDK

When the SDK is properly installed you should see, e.g.:

$ gcloud -v
Google Cloud SDK 232.0.0
bq 2.0.40
core 2019.01.27
gsutil 4.35

gcloud auth login

Sets authentication credentials for the gcloud command-line utility

gcloud auth application-default login

Sets "Application Default Credentials" for use by the @google-cloud Node.js SDKs.

gcloud config set project <project id>

Set the current active "project" for the gcloud CLI.

gcloud app create

Follow the prompts to initialize your project for "App Engine". You'll be asked to choose a region for your app. This cannot be changed later.

Usage

In the same way that your site leverages npm to version and install the library code that it uses, @carnesen/google-cloud leverages npm to version and install the site code that it deploys. This usage example assumes you've already completed the setup in the "Install" section above. We use npm to pull down the site code that we want to deploy:

npm install --save @carnesen/redirector @carnesen/www github:carnesen/meme-me @carnesen/run-and-exit

For deploying a single site, your deployment code might even be co-located with the application code in which case you wouldn't need to npm install anything beyond @carnesen/google-cloud.

Create a Node.js script deploy.js with contents:

const runAndExit = require('@carnesen/run-and-exit');
const { deployApp } = require('@carnesen/google-cloud');

// In the context of this library is an "App" is a Google Cloud
// App Engine "App", which is comprised of one or more websites
runAndExit(deployApp, {
  projectId: '<project id>',
  zoneName: '<zone name>',
  defaultSite: {
    siteType: 'nodejs',
    packageId: '@carnesen/redirector',
  },
  otherSites: [
    {
      siteType: 'static',
      siteName: 'www',
      packageId: '@carnesen/www',
    },
    {
      siteType: 'nodejs',
      siteName: 'meme-me',
      packageId: '@carnesen/meme-me',
    },
  ],
});

And run it:

$ node deploy.js
AppEngine : carnesen-tmp : Creating...
AppEngine : carnesen-tmp : Already exists
Site : default : Pre-validating...
Site : www : Pre-validating...
Site : meme-me : Pre-validating...
...

API

This project's API is documented in the form of TypeScript types and TSDoc strings.

Conventions

This project favors convention over configuration, and hopefully the conventions will align pretty well with what you're already doing. As mentioned above, for both Node.js and static sites, the site content must be in a place where require.resolve(`${packageId}/package.json`) will return the path of a package.json file. That file's containing directory is what gets uploaded to Google Cloud App Engine using gcloud app deploy.

nodejs

The package directory is uploaded to Google Cloud as-is. In particular that means that npm start should fire up your Node.js server process.

static

Similar to Node.js sites, the package directory is uploaded to Google Cloud as-is. The root of the package, however, is not what gets served by App Engine. Instead by convention it's assumed that the dist subdirectory that contains the static content that you want to serve. If that convention doesn't suit you, please just let me know and I'd be happy to parameterize it.

More information

This library doesn't have many unit tests, but I use it on a semi-regular basis to deploy sites to carnesen.com. To be sure, I don't get much traffic on those sites, but my GCP bill is typically less than a dollar a month! If you encounter any bugs or have any questions or feature requests, please don't hesitate to file an issue or submit a pull request on this project's repository on GitHub.

Related

License

MIT © Chris Arnesen