Skip to content

Latest commit

 

History

History
211 lines (152 loc) · 5.66 KB

INSTALL.md

File metadata and controls

211 lines (152 loc) · 5.66 KB
Raw

GitHub badges in SVG format

npm version

coverage

build status

Make your own badges here! (Quick guide: https://img.shields.io/badge/left-right-f39f37.svg.)

Install the API

npm install gh-badges
var badge = require('gh-badges');
// Optional step, to have accurate text width computation.
badge.loadFont('/path/to/Verdana.ttf', function(err) {
  badge({ text: ["build", "passed"], colorscheme: "green", template: "flat" },
    function(svg, err) {
      // svg is a String of your badge.
    });
});

Use the CLI

npm install -g gh-badges
badge build passed :green .png > mybadge.png
# Stored a PNG version of your badge on disk.

Start the Server

To run the server you will need the following executables on your Path:

On an OS X machine, Homebrew is a good package manager that will allow you to install that.

On Ubuntu / Debian: sudo apt-get install phantomjs.

You will also need version 6 of Node.js. The Node.js documentation explains how to install it on various systems. 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.
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 http://shields.io. For testing purposes, you can go to http://localhost/try.html.

Format

The format is the following:

{
  /* Textual information shown, in order. */
  "text": [ "build", "passed" ],
  "format": "svg",  // Also supports "json".
  "colorscheme": "green",
  /* … Or… */
  "colorA": "#555",
  "colorB": "#4c1",
  /* See templates/ for a list of available templates.
     Each offers a different visual design. */
  "template": "flat"
}

See also

Defaults

If you want to add a colorscheme, head to lib/colorscheme.json. Each scheme has a name and a CSS/SVG color for the color used in the first box (for the first piece of text, field colorA) and for the one used in the second box (field colorB).

"green": {
  "colorB": "#4c1"
}

Both colorA and colorB have default values. Usually, the first box uses the same dark grey, so you can rely on that default value by not providing a "colorA" field (such as above).

You can also use the "colorA" and "colorB" fields directly in the badges if you don't want to make a color scheme for it. In that case, remove the "colorscheme" field altogether.

Making your Heroku badge server

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 secret.example.env for an example.

Then run the container:

$ docker run --rm -p 8080:80 --env-file shields.env --name shields shields

> [email protected] start /usr/src/app
> node server.js

http://[::1]:80/try.html

Assuming Docker is running locally, you should be able to get to the application at http://localhost:8080/try.html. If you run Docker in a virtual machine (such as boot2docker or Docker Machine) then you will need to replace localhost with the actual IP address of that virtual machine.

Build the index

Build the "real" index page:

make website

Secret.json

Some services require the use of secret tokens or passwords. Those are stored in private/secret.json which is not checked into the repository, to avoid impersonation. Here is how it currently looks like:

bintray_apikey
bintray_user
gh_client_id
gh_client_secret
gh_token
gitter_dev_secret
shieldsIps
shieldsSecret
sl_insight_apiToken
sl_insight_userUuid

(Gathered from cat private/secret.json | jq keys | grep -o '".*"' | sed 's/"//g'.)

The secret.tpl.json is a template file used by the Docker container to set the secrets based on environment variables.

Main Server Sysadmin

  • Servers in DNS round-robin:
    • s0: 192.99.59.72 (vps71670.vps.ovh.ca)
    • s1: 51.254.114.150 (vps244529.ovh.net)
    • s2: 149.56.96.133 (vps117870.vps.ovh.ca)
  • Self-signed TLS certificates, but img.shields.io is behind CloudFlare, which provides signed certificates.
  • Using systemd to automatically restart the server when it crashes.

See https://github.com/badges/ServerScript for helper admin scripts.

Links

See h5bp/lazyweb-requests#150 for a story of the project's inception.

This is also available as a gem badgerbadgerbadger, code here.

License

All work here is licensed CC0.