Hosting your own Shields server
This document describes how to host your own shields server either from source or using a docker image. See the docs on releases for info on how we version the server and how to choose a release.
Installing from Source
You will need Node 18 or later, which you can install using a package manager.
On Ubuntu / Debian:
curl -sL https://deb.nodesource.com/setup_18.x | sudo -E bash -; sudo apt-get install -y nodejs
git clone https://github.com/badges/shields.git cd shields git checkout $(git tag | grep server | tail -n 1) # checkout the latest tag npm ci # You may need sudo for this.
Build the frontend
npm run build
Start the server
sudo node server
The server uses port 80 by default, which requires
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
Deploying to Heroku
Once you have installed the Heroku CLI
heroku login heroku create your-app-name git push heroku master heroku open
Deploying to Zeit Vercel
To deploy using Zeit Vercel:
npm run build # Not sure why, but this needs to be run before deploying. vercel
We publish images to:
- DockerHub at https://registry.hub.docker.com/r/shieldsio/shields and
- GitHub Container Registry at https://github.com/badges/shields/pkgs/container/shields
next tag is the latest build from
master, or tagged snapshot releases are available:
# DockerHub $ docker pull shieldsio/shields:next $ docker run shieldsio/shields:next
# GHCR $ docker pull ghcr.io/badges/shields:next $ docker pull ghcr.io/badges/shields:next
Building Docker Image Locally
Alternatively, 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, alter the default values for configuration by setting them via environment variables.
See server-secrets.md and config/custom-environment-variables.yml for possible values.
In config/custom-environment-variables.yml, environment variable names are specified as the quoted, uppercase key values (e.g.
Then run the container, and be sure to specify the same mapped port as the one Shields is listening on :
$ docker run --rm -p 8080:8080 --env PORT=8080 --name shields shieldsio/shields:next Configuration: ... 0916211515 Server is starting up: http://0.0.0.0:8080/
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
If you want to host PNG badges, you can also self-host a raster server which points to your badge server. It's a docker container. We host it on Fly.io but should be possible to host on a wide variety of platforms.
- In your raster instance, set
BASE_URLto your Shields instance, e.g.
- Optionally, in your Shields, instance, configure
RASTER_URLto the base URL, e.g.
https://raster.example.co. This will send 301 redirects for the legacy raster URLs instead of 404's.
If anyone has set this up, more documentation on how to do this would be welcome!
You can add your own server secrets in environment variables or
These are documented in server-secrets.md
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.
BASE_URL=https://your-server.example.com npm run build
Then copy the contents of the
public/ folder to your static hosting / CDN.
There are also a couple settings you should configure on the server.
To help out users, you can make the Shields server redirect the server root.
REDIRECT_URI environment variable:
How to obtain the Sentry DSN
- 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:
sudo SENTRY_DSN=https://xxx:firstname.lastname@example.org/zzz node server
Or via config as you would do with server secrets:
private: sentry_dsn: ...
sudo node server
Shields uses prom-client to provide default metrics. These metrics are disabled by default.
You can enable them by
METRICS_PROMETHEUS_ENDPOINT_ENABLED environment variables.
METRICS_PROMETHEUS_ENABLED=true METRICS_PROMETHEUS_ENDPOINT_ENABLED=true npm start
Metrics are available at
Shields.io uses Cloudflare as a downstream CDN. If your installation does the same,
you can configure your server to only accept requests coming from Cloudflare's IPs.