shields/doc/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

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

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 --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.

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. Just copy the built index.html there.

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

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