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.
LONG_CACHE=true npm run build
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/
.
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
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
> [email protected] 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.
To deploy using Zeit Now:
npm run build # Not sure why, but this needs to be run before deploying.
now
To enable Redis-backed GitHub token persistence, point REDIS_URL
to your
Redis installation.
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.
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/
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}
.
- 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:[email protected]/zzz node server
- or by
sentry_dsn
secret property defined inprivate/secret.json
sudo node server