Introduction to Shields.io
Shields.io is a popular service that provides concise, consistent, and legible badges for your GitHub projects, documentation, and websites. These badges are useful for displaying various metrics like build status, version numbers, downloads, license information, and more. They help make your repositories more informative and professional by providing visual indicators of your project’s status and other key information.
Some common use cases for Shields.io badges include:
- Displaying build status (passing/failing)
- Showing package version numbers
- Indicating code coverage percentages
- Displaying download counts
- Showing license information
- Custom status badges for any project metric
While Shields.io offers a free public service, there are several compelling reasons to self-host your own instance:
- Reliability: Your badges remain accessible even if the public Shields.io service experiences downtime
- Privacy: Access to private repositories and services without exposing credentials to a third party
- Performance: Reduced latency, especially for internal projects
- Customization: Full control over the instance configuration and appearance
- No rate limits: Avoid hitting the public service rate limits, especially for GitHub API requests
In this guide, we’ll walk you through setting up your own Shields.io instance using Docker, which makes deployment straightforward and portable.
Prerequisites
Before getting started, make sure you have:
- A server or VM with Docker installed
- Docker Compose (recommended for easier management)
- Basic knowledge of Docker and containerization
- Any API tokens or credentials for services you want to use with Shields.io (GitHub, GitLab, etc.)
Self-Hosting Using Docker
Shields.io provides official Docker images that make deployment straightforward. There are two main approaches to running your Shields.io instance with Docker:
- Using the official image directly
- Using Docker Compose for more flexibility
Option 1: Using the Official Docker Image
The Shields.io team maintains official Docker images on both DockerHub and GitHub Container Registry:
- DockerHub: shieldsio/shields
- GitHub Container Registry: ghcr.io/badges/shields
To run a basic Shields.io instance, you can use the following command:
|
1 2 3 |
docker run --rm -p 8080:8080 --env PORT=8080 --name shields shieldsio/shields:next |
This command will:
- Pull the latest development build from the Docker registry
- Run the container named “shields”
- Map port 8080 on your host to port 8080 in the container
- Remove the container when it stops (using the
--rmflag)
Once running, you can access your Shields.io instance at http://localhost:8080/.
Option 2: Using Docker Compose (Recommended)
For a more robust deployment, you can use Docker Compose to manage your Shields.io instance. Here’s a basic docker-compose.yml file to get you started:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 |
version: '3' services: shields: image: shieldsio/shields:next container_name: shields restart: always ports: - "8080:8080" environment: - PORT=8080 # Uncomment and update the following if you want to use GitHub authentication # - GH_TOKEN=your-github-token volumes: # Optional volume for local configuration - ./config:/usr/local/shields/config # Optional: Add a caching layer with Varnish varnish: image: varnish:stable container_name: shields-varnish restart: always ports: - "80:80" depends_on: - shields environment: - VARNISH_SIZE=2G volumes: - ./varnish/default.vcl:/etc/varnish/default.vcl |
To run your Shields.io instance with Docker Compose:
|
1 2 3 |
docker-compose up -d |
This will start both the Shields.io service and a Varnish caching layer in detached mode.
Configuration Options
Shields.io offers numerous configuration options that can be set via environment variables. Here are some of the most important ones:
Core Settings
PORT: The port the server will listen on (default: 80)REDIRECT_URI: Where to redirect the server root (useful with CDN hosting)BASE_URL: URL where your Shields instance is deployed, used for building badge URLs
Service Authentication
To avoid rate limits and access private repositories, you can add authentication tokens for various services. Here are some common ones:
GitHub
|
1 2 3 4 |
environment: - GH_TOKEN=your-github-personal-access-token |
GitHub has a rate limit of 60 requests per hour for unauthenticated requests, which can be quickly exhausted. Adding a GitHub token significantly increases this limit and allows access to private repositories. Create a Personal Access Token (PAT) with at least the repo scope.
GitLab
|
1 2 3 4 5 |
environment: - GITLAB_ORIGINS=https://gitlab.example.com - GITLAB_TOKEN=your-gitlab-personal-access-token |
Docker Hub
|
1 2 3 4 5 |
environment: - DOCKERHUB_USER=your-dockerhub-username - DOCKERHUB_PAT=your-dockerhub-personal-access-token |
NPM
|
1 2 3 4 |
environment: - NPM_TOKEN=your-npm-token |
Server Secrets
For more complex configurations, you can create a config/local.yml file:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
public: services: github: baseUri: https://github.example.com/api/v3/ gitlab: authorizedOrigins: ['https://gitlab.example.com'] private: gh_token: 'your-github-token' gitlab_token: 'your-gitlab-token' |
Mount this file as a volume in your Docker container:
|
1 2 3 4 |
volumes: - ./config:/usr/local/shields/config |
PNG Badge Support with Raster Server
Shields.io primarily serves SVG badges, but if you need PNG badges, you can set up a raster server:
- In your raster instance, set
BASE_URLto your Shields instance, e.g.,https://shields.example.com - In your Shields instance, configure
RASTER_URLto point to your raster server, e.g.,https://raster.example.com
This will enable Shields to redirect legacy raster URLs to your raster server.
Advanced Configuration
Monitoring with Prometheus
Shields.io supports Prometheus metrics, which can be enabled with:
|
1 2 3 4 5 6 |
environment: - METRICS_PROMETHEUS_ENABLED=true - METRICS_PROMETHEUS_ENDPOINT_ENABLED=true |
Metrics will be available at the /metrics endpoint.
Sentry Integration
For error tracking, you can integrate with Sentry:
|
1 2 3 4 5 |
environment: - SENTRY_DSN=https://{PUBLIC_KEY}:{SECRET_KEY}@sentry.io/{PROJECT_ID} |
CDN / Frontend Hosting
You can host the frontend separately if desired:
- Build the frontend pointing to your server:
BASE_URL=https://your-server.example.com npm run build - Copy the contents of the
public/folder to your static hosting or CDN - Configure the Shields server to redirect to your CDN:
environment: - REDIRECT_URI=https://your-cdn.example.com/
Security Considerations
When self-hosting Shields.io, keep these security considerations in mind:
- API Tokens: Use tokens with the minimum required permissions. For GitHub, a read-only token is sufficient.
- HTTPS: Always use HTTPS for your Shields instance to protect tokens and credentials.
- Restrictive Network Access: Consider restricting access to your Shields instance to your internal network if it’s only used internally.
- Regular Updates: Keep your Docker images updated to get security patches.
Troubleshooting
Common Issues
- Badge Not Found (404): Check if the requested service is properly configured and has the necessary tokens.
- Rate Limit Exceeded: Verify that your API tokens are correctly configured.
- Authentication Errors: Ensure your tokens have the correct permissions and haven’t expired.
- Connectivity Issues: Make sure your server can reach the external services needed for badge generation.
Logs
To view logs for your Shields.io instance:
|
1 2 3 4 5 6 |
docker logs shields # Or with Docker Compose docker-compose logs shields |
Thoughts
Self-hosting Shields.io with Docker provides flexibility, privacy, and reliability for your badges. Whether you’re using it for public or private repositories, having your own instance ensures your badges are always available and don’t suffer from rate limiting issues.
By following this guide, you should have a fully functional Shields.io instance running in Docker that can be customized to suit your specific needs. The combination of Docker containerization and Shields.io’s flexible configuration options makes for a powerful and maintainable badge service.
For more detailed information, refer to the official Shields.io documentation and the Docker image repository.
