self-hosting.md

Hosting your own Shields server

Installation

You will need version 6 of Node.js, which you can install using a package manager.

On Ubuntu / Debian:

curl -sL https://deb.nodesource.com/setup_6.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

LONG_CACHE=true 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
cp /path/to/Verdana.ttf .
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 shields.example.env for an example.

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

Server secrets

You can add your own server secrets in private/secret.json.

Because of Github rate limits, you will need to provide a token, or else badges will stop working once you hit 60 requests per hour, the unauthenticated rate limit.

You can create a personal access token through the Github website. When you create the token, you can choose to give read access to your repositories. If you do that, your self-hosted Shields installation will have access to your private repositories.

{
  "gh_token": "..."
}

When a gh_token is specified, it is used in place of the Shields token rotation logic.

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 BASE_URL to your server.

LONG_CACHE=true 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/