Skip to content

Latest commit

 

History

History
170 lines (123 loc) · 4.68 KB

INSTALL.md

File metadata and controls

170 lines (123 loc) · 4.68 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.

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. You should modify that file. The "real" root, http://localhost/index.html, gets generated from the try.html file.

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 template/ for a list of available templates.
     Each offers a different visual design. */
  "template": "flat"
}

Defaults

If you want to add a colorscheme, head to 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
Step 0 : FROM node:0.12.7-onbuild
…
Removing intermediate container c4678889953f
Successfully built 4471b442c220

Then run the container:

$ docker run --rm -p 8080:80 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.

Main Server Sysadmin

  • DNS round-robin between https://vps197850.ovh.net/try.html and https://vps244529.ovh.net/try.html.
  • Self-signed TLS certificates, but img.shields.io is behind CloudFlare, which provides signed certificates.
  • Using node v0.12.7 because later versions, combined with node-canvas, give inaccurate badge measurements.
  • Using forever (the node monitor) 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.