Generates a dynamic progress bar image (SVG) using Python, served behind Cloudflare from Render (with Vercel as a fallback) β or self-hosted on your own server.
π Preview:
The public instance is available at progress-bar.xyz β just use https://progress-bar.xyz/{number}/ as an image URL in any Markdown or HTML.
| Layer | Provider | Status |
|---|---|---|
| DNS / CDN | Cloudflare (free plan) | β Active β TLS, edge caching of the SVGs, origin hidden behind the proxy |
| Origin | Render | β
Active β primary, auto-deploys from main |
| Fallback | Vercel | βΈοΈ Paused β see below |
Because the domain is on Cloudflare, switching origins (Render β Vercel β a self-hosted VM) is a single DNS change, with no change to the badge URLs.
Note
Why Vercel is paused: the Hobby plan counts every request β cached or not β against a monthly quota (1M requests). Badges are re-fetched by GitHub's image proxy on every README render, and the badge route used to send no Cache-Control header, so the quota ran out and Vercel disabled the deployment (HTTP 402 DEPLOYMENT_DISABLED), taking the service offline β reported in #276.
#278 fixed the root cause by adding cache headers, a /health endpoint and a self-hosting runtime; the service was then moved to Render behind Cloudflare. The Vercel deployment is kept as a fallback and still works from the same code.
| π§ Parameter | π Description | π― Default Value |
|---|---|---|
title |
Adds a title to the progress bar | None |
scale |
The maximum value that the progress bar represents | 100 |
as_percent |
With scale, show the number as a percentage of the scale |
false |
prefix |
A string to add before the progress number | None |
suffix |
A string to add after the progress number | % |
width |
The width of the progress bar in pixels | 60 with a title, 90 without |
color |
The color of the title area (hex code without #) |
428bca (blue) |
progress_background |
The background color of the progress bar (hex code without #) |
555 (grey) |
progress_number_color |
The color of the progress number (hex code without #) |
fff (white) |
progress_color |
The color of the progress bar (hex code without #) |
Depends on percentage |
show_text |
Whether to display or hide the progress text | true |
show_shadow |
Whether to draw the text shadow | true |
radius |
Corner radius in pixels | 4 |
style |
The style. One of: default, flat, square, plastic, for-the-badge, thin-rounded, neo-glass, minimal-matte |
default |
origin |
Where the bar fills from: left, center (alias middle) or right. With center, zero is the middle of the bar β positive values grow right and negative values grow left (like Excel data bars) |
left |
negative_color |
Color of the bar for negative values (hex code without #). Overrides progress_color and the style color when the value is below zero |
Depends on percentage |
Below are several examples showcasing different ways to generate progress bars.
Negative numbers are accepted (e.g. /-28/). The bar length is the absolute value relative to scale, and the sign is kept in the text.
Use origin=center to get Excel-style data bars, which are handy for a column of positive and negative values in a Markdown table: each side of the middle axis spans scale.
origin and negative_color also work with /dynamic/json/, so a negative number read from a JSON document renders the same way.
We currently support:
| π¨ Style | π Preview | π URL |
|---|---|---|
| π’ flat (default) | https://progress-bar.xyz/100/?style=flat | |
| π² square | https://progress-bar.xyz/100/?style=square | |
| π‘οΈ plastic | https://progress-bar.xyz/100/?style=plastic | |
| π for-the-badge | https://progress-bar.xyz/100/?style=for-the-badge | |
| π thin-rounded | https://progress-bar.xyz/100/?style=thin-rounded | |
| πͺ neo-glass | https://progress-bar.xyz/100/?style=neo-glass | |
| π¨ minimal-matte | https://progress-bar.xyz/100/?style=minimal-matte |
Besides a fixed value in the path (/75/), you can load the number from a remote JSON file.
Sample JSON file: https://raw.githubusercontent.com/guibranco/progressbar/main/docs/dynamic-json-sample.json
Use query parameters:
| Parameter | Description |
|---|---|
url |
Required. Address of the JSON document (http or https). Must be URL-encoded in the query string. |
query |
Required. JSONPath (e.g. $.items[0].metrics.pct) or dot form from the root (e.g. items.0.metrics.pct). Filter expressions are supported, so you can look up a value by a sibling field instead of a hardcoded index β e.g. $.progress[?(@.data.language.name=='Spanish')].data.translationProgress. |
cache |
Optional. Cache-Control max-age in seconds (alias cacheSeconds), between 0 and 86400. Default: 300. 0 disables caching for that request. |
Any other parameters from the table above (title, scale, style, β¦) apply the same way as on /{number}/.
Badges are fetched by GitHub's image proxy (camo), browsers and CDNs on every README render, so every response carries a Cache-Control header:
| Route | Cache-Control |
|---|---|
/{number}/ |
public, max-age=604800, s-maxage=604800, stale-while-revalidate=604800 β the SVG is fully determined by the URL, so it is safe to cache for a week |
/dynamic/json/ |
public, max-age=300, s-maxage=300 by default; override per request with cache= |
/favicon.ico |
public, max-age=2592000, s-maxage=2592000, stale-while-revalidate=604800 (30 days) |
/robots.txt |
public, max-age=2592000, s-maxage=2592000 (30 days) |
/.well-known/security.txt |
public, max-age=86400, s-maxage=86400 (1 day β its Expires field moves forward daily) |
Errors, /health |
no-store |
The two defaults can be changed per deployment with the environment variables PROGRESSBAR_STATIC_CACHE_SECONDS (0β2592000, default 7 days) and PROGRESSBAR_DYNAMIC_CACHE_SECONDS (0β86400). Keep in mind that changes to a badge's look can take up to the configured static TTL (7 days by default, up to 30 days if PROGRESSBAR_STATIC_CACHE_SECONDS is raised) to show up in READMEs β and a CDN that honours stale-while-revalidate may keep serving the previous version for up to another 7 days while it refreshes the entry in the background.
You can run your own instance in one click on Render or Vercel, or on any server that runs Docker or Python. The app is stateless and needs no database or secrets.
The button reads render.yaml and creates a Docker web service from the repository's Dockerfile, with /health as the health check and auto-deploy on every push.
- On the Free instance type the service spins down after ~15 minutes without traffic, and the next request waits for a cold start (up to about a minute). Putting a CDN such as Cloudflare in front (so most badges are served from its cache), pinging
/healthperiodically, or using a paid instance type avoids that. - Custom domain on Cloudflare: add the domain in Render (Settings β Custom Domains), create a
CNAMEpointing to<service>.onrender.comin Cloudflare with the proxy off (DNS only) until Render verifies it and issues the certificate, then turn the proxy on and use SSL mode Full (strict).
Vercel uses vercel.json and the @vercel/python runtime; no extra configuration is needed.
Warning
The Hobby plan counts every request (cached or not) against its monthly quota. When it runs out, Vercel pauses the deployment and it stays offline until you unpause it in the dashboard or upgrade β this is what happened to the public instance (#276). The cache headers keep most renders away from Vercel, but for a popular badge prefer Render or your own server.
The same code runs anywhere Python runs. The repository ships everything needed for a small VM (1 vCPU / 1 GB is plenty β the app is stateless and serves ~1.8 KB per badge in about a millisecond):
| File | Purpose |
|---|---|
Dockerfile, compose.yaml |
gunicorn (threaded workers) on 127.0.0.1:8099, non-root, with a Docker healthcheck |
gunicorn.conf.py |
Sizing/logging knobs, all overridable via PROGRESSBAR_* environment variables (deploy/env.example) |
deploy/nginx/ |
NGINX reverse proxy with a response cache (proxy_cache), so Python only runs on cache misses |
deploy/systemd/ |
systemd units for the compose stack, or for bare-metal gunicorn without Docker |
deploy/install.sh, deploy/update.sh |
First-time setup and redeploy scripts for the VM |
.github/workflows/deploy.yml |
Optional CI deploy over SSH after CI passes on main (opt-in via SELF_HOST_DEPLOY=true) |
An Ubuntu host (tested on 24.04) with git, curl, Docker with the compose plugin, and NGINX, plus a DNS record for your domain pointing to the server:
sudo apt update && sudo apt install -y git curl nginx certbot python3-certbot-nginx
curl -fsSL https://get.docker.com | sudo shinstall.sh clones the repository to /opt/progressbar/app, installs the NGINX vhost and cache, builds and starts the container, registers the systemd unit and runs a smoke test. Export DOMAIN (and optionally APP_DIR, BRANCH, DEPLOY_USER) to override the defaults:
curl -fsSLO https://raw.githubusercontent.com/guibranco/progressbar/main/deploy/install.sh
less install.sh # review before running it as root
sudo DOMAIN=badges.example.com bash install.sh
sudo certbot --nginx -d badges.example.com # TLSOptional settings (cache TTLs, gunicorn workers/threads, logging) go in deploy/env β copy deploy/env.example.
curl -fsS http://127.0.0.1:8099/health # {"status": "ok"}
curl -sI https://badges.example.com/58/ | grep -i x-cache # MISS, then HIT on the second callcd /opt/progressbar/app && deploy/update.shupdate.sh fetches main (or an exact commit via DEPLOY_SHA), rebuilds the image, restarts the container and waits for /health; if the new container never becomes healthy it rolls back to the previous image.
To deploy automatically after CI passes on main, set the repository variable SELF_HOST_DEPLOY=true (and optionally SELF_HOST_APP_DIR) and the secrets DEPLOY_SSH_HOST, DEPLOY_SSH_USER, DEPLOY_SSH_KEY, DEPLOY_SSH_KNOWN_HOSTS (and optionally DEPLOY_SSH_PORT). The workflow in .github/workflows/deploy.yml then runs update.sh over SSH.
git clone https://github.com/guibranco/progressbar.git && cd progressbar
python3 -m venv venv && venv/bin/pip install --require-hashes -r requirements.txt
venv/bin/gunicorn -c gunicorn.conf.py app:app # http://127.0.0.1:8099/58/Use deploy/systemd/progressbar-gunicorn.service to run it as a service and deploy/nginx/ for the reverse proxy.
GET /health returns {"status": "ok"} for uptime monitors and load balancers. Put the domain behind a CDN/proxy such as Cloudflare's free plan (proxied record, SSL mode Full (strict)) to get edge caching and to be able to switch origins β your server, Render or Vercel β without touching the app or the badge URLs.
The app serves an RFC 9116 /.well-known/security.txt (and redirects the legacy /security.txt to it) with the fields Cloudflare's security.txt generator asks for: Contact, Expires, Policy, Preferred-Languages and Canonical. Expires is always 180 days from the current day, so the file never goes stale and needs no yearly update. Because the app answers this path itself, leave Cloudflare's own Security.txt setting (Security β Settings) disabled for the zone, or Cloudflare will serve its version instead.
Running your own instance on another domain? Point the fields at your own contacts with PROGRESSBAR_SECURITY_CONTACT (comma-separated mailto:/https:// URIs), PROGRESSBAR_SECURITY_POLICY, PROGRESSBAR_SECURITY_CANONICAL and PROGRESSBAR_SECURITY_LANGUAGES (see deploy/env.example); set any of the last three to an empty value to omit that field.
Check out CONTRIBUTING.md to learn how to contribute!
|
Guilherme Branco Stracini |
nimble-turtle |
ztest95 |
David Nwosu |
Eduardo Baptista |
bhosley |
|
dependabot[bot] |
github-actions[bot] |
penify-dev[bot] |
deepsource-autofix[bot] |
Snyk bot |
This project is licensed under the MIT License.
π See LICENSE for details.