Files

Paul Melnikow d8ce045ead Adopt Gatsby (#2906 )

While Next.js can handle static sites, we've had a few issues with it, notably a performance hit at runtime and some bugginess around routing and SSR. Gatsby being fully intended for high-performance static sites makes it a great technical fit for the Shields frontend. The `createPages()` API should be a really nice way to add a page for each service family, for example.

This migrates the frontend from Next.js to Gatsby. Gatsby is a powerful tool, which has a bit of downside as there's a lot to dig through. Overall I found configuration easier than Next.js. There are a lot of plugins and for the most part they worked out of the box. The documentation is good.
 Links are cleaner now: there is no #. This will break old links though perhaps we could add some redirection to help with that. The only one I’m really concerned about `/#/endpoint`. I’m not sure if folks are deep-linking to the category pages.

There are a lot of enhancements we could add, in order to speed up the site even more. In particular we could think about inlining the SVGs rather than making separate requests for each one.

While Gatsby recommends GraphQL, it's not required. To keep things simple and reduce the learning curve, I did not use it here.

Close #1943 
Fix #2837 Fix #2616

2019-02-06 16:37:55 -05:00

4.9 KiB

Raw Blame History

Hosting your own Shields server

Installation

You will need Node 8 or later, which you can install using a package manager.

On Ubuntu / Debian:

curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -; sudo apt-get install -y nodejs

git clone https://github.com/badges/shields.git
cd shields
npm install  # You may need sudo for this.

Build the frontend

npm run build

Start the server

sudo node server

The server uses port 80 by default, which requires sudo permissions.

There are two ways to provide an alternate port:

PORT=8080 node server
node server 8080

The root gets redirected to https://shields.io.

For testing purposes, you can go to http://localhost/.

Heroku

Once you have installed the Heroku Toolbelt:

heroku login
heroku create your-app-name
heroku config:set BUILDPACK_URL=https://github.com/mojodna/heroku-buildpack-multi.git#build-env
make deploy
heroku open

Docker

You can build and run the server locally using Docker. First build an image:

$ docker build -t shields .
Sending build context to Docker daemon 3.923 MB
…
Successfully built 4471b442c220

Optionally, create a file called shields.env that contains the needed configuration. See server-secrets.md and ../config/custom-environment-variables.yml for examples.

Then run the container:

$ docker run --rm -p 8080:80 --name shields shields
# or if you have shields.env file, run the following instead
$ docker run --rm -p 8080:80 --env-file shields.env --name shields shields

> gh-badges@1.1.2 start /usr/src/app
> node server.js

http://[::1]/

Assuming Docker is running locally, you should be able to get to the application at http://localhost:8080/.

If you run Docker in a virtual machine (such as boot2docker or Docker Machine) then you will need to replace localhost with the IP address of that virtual machine.

Zeit Now

To deploy using Zeit Now:

npm run build  # Not sure why, but this needs to be run before deploying.
now

Persistence

To enable Redis-backed GitHub token persistence, point REDIS_URL to your Redis installation.

Server secrets

You can add your own server secrets in environment variables or config/local.yml.

These are documented in server-secrets.md

Separate frontend hosting

If you want to host the frontend on a separate server, such as cloud storage or a CDN, you can do that.

First, build the frontend, pointing GATSBY_BASE_URL to your server.

GATSBY_BASE_URL=https://your-server.example.com npm run build

Then copy the contents of the build/ folder to your static hosting / CDN.

There are also a couple settings you should configure on the server.

If you want to use server suggestions, you should also set ALLOWED_ORIGIN:

ALLOWED_ORIGIN=http://my-custom-shields.s3.amazonaws.com,https://my-custom-shields.s3.amazonaws.com

This should be a comma-separated list of allowed origin headers. They should not have paths or trailing slashes.

To help out users, you can make the Shields server redirect the server root. Set the REDIRECT_URI environment variable:

REDIRECT_URI=http://my-custom-shields.s3.amazonaws.com/

Sentry

In order to enable integration with Sentry, you need your own Sentry DSN. It’s an URL in format https://{PUBLIC_KEY}:{SECRET_KEY}@sentry.io/{PROJECT_ID}.

How to obtain the Sentry DSN

Sign up for Sentry
Log in to Sentry
Create a new project for Node.js
You should see Sentry DSN for your project. Sentry DSN can be found by navigating to [Project Name] -> Project Settings -> Client Keys (DSN) as well.

Start the server using the Sentry DSN. You can set it:

by SENTRY_DSN environment variable

sudo SENTRY_DSN=https://xxx:yyy@sentry.io/zzz node server

or by sentry_dsn secret property defined in private/secret.json

sudo node server

Prometheus

Shields uses prom-client to provide default metrics. These metrics are disabled by default. You can enable them by METRICS_PROMETHEUS_ENABLED environment variable. Moreover access to metrics resource is blocked for requests from any IP address by default. You can provide a regular expression with allowed IP addresses by METRICS_PROMETHEUS_ALLOWED_IPS environment variable.

METRICS_PROMETHEUS_ENABLED=true METRICS_PROMETHEUS_ALLOWED_IPS="^127\.0\.0\.1$" npm start

Metrics are available at /metrics resource.

4.9 KiB Raw Blame History Unescape Escape