Skip to content

About

πŸš€πŸ“Š Generates a dynamic progress bar image in SVG format, perfect for badges, dashboards, and visual indicators. Customize colors, sizes, and progress values with ease!

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

106 stars

Watchers

0 watching

Forks

Repository files navigation

πŸš€ Dynamic Progress Bar

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.

Deploy to Render Deploy with Vercel

πŸ“Š Preview:

Progress Progress Progress

Inspired by fredericojordan/progress-bar.


πŸ”₯ Other Projects

  • ⭐ Star Rating Dynamic Star Rating - GoulartNogueira/Star-Rating

πŸ› οΈ Usage

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.

🌐 Hosting

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.


βš™οΈ Parameters

πŸ”§ 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

Examples

Below are several examples showcasing different ways to generate progress bars.

πŸ“Œ Preview 🌐 URL
Progress https://progress-bar.xyz/28/
Progress https://progress-bar.xyz/28/?title=progress
Progress https://progress-bar.xyz/58/
Progress https://progress-bar.xyz/58/?title=completed
Progress https://progress-bar.xyz/91/
Progress https://progress-bar.xyz/91/?title=done
Progress https://progress-bar.xyz/180/?scale=10&title=mark&prefix=R$&suffix=
Progress https://progress-bar.xyz/420/?scale=500&title=funds&width=200&color=babaca&prefix=R$&suffix=
Progress https://progress-bar.xyz/7/?scale=10&title=mark&suffix=X
Progress https://progress-bar.xyz/420/?scale=500&title=funds&width=200&color=babaca&suffix=$
Progress https://progress-bar.xyz/58/?title=colorful&progress_background=ffc0cb&progress_number_color=000
Progress https://progress-bar.xyz/100/?progress_color=ff3300
Progress https://progress-bar.xyz/100/?width=100&title=Fixed+color&progress_color=ff3300
Progress https://progress-bar.xyz/28/?show_text=false
Progress https://progress-bar.xyz/90/?show_text=false
Progress from JSON https://progress-bar.xyz/dynamic/json/?url=https%3A%2F%2Fraw.githubusercontent.com%2Fguibranco%2Fprogressbar%2Fmain%2Fdocs%2Fdynamic-json-sample.json&query=demo.metrics.translationPercent&title=JSON%20Demo
Progress from JSON https://progress-bar.xyz/dynamic/json/?url=https%3A%2F%2Fraw.githubusercontent.com%2Fguibranco%2Fprogressbar%2Fmain%2Fdocs%2Fdynamic-json-sample.json&query=demo.metrics.translationPercent

βž– Negative values and data 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.

πŸ“Œ Preview 🌐 URL
Progress https://progress-bar.xyz/-28/
Progress https://progress-bar.xyz/75/?origin=center&title=delta
Progress https://progress-bar.xyz/-40/?origin=center&title=delta
Progress https://progress-bar.xyz/-30/?origin=center&scale=50&width=120&progress_color=3b82f6&negative_color=d9534f&suffix=
Progress https://progress-bar.xyz/60/?origin=right&title=rtl

origin and negative_color also work with /dynamic/json/, so a negative number read from a JSON document renders the same way.

🎨 Styles

We currently support:

🎨 Style πŸ“Œ Preview 🌐 URL
🟒 flat (default) Progress https://progress-bar.xyz/100/?style=flat
πŸ”² square Progress https://progress-bar.xyz/100/?style=square
πŸ›‘οΈ plastic Progress https://progress-bar.xyz/100/?style=plastic
πŸ”– for-the-badge Progress https://progress-bar.xyz/100/?style=for-the-badge
🎭 thin-rounded Progress https://progress-bar.xyz/100/?style=thin-rounded
πŸͺž neo-glass Progress https://progress-bar.xyz/100/?style=neo-glass
🎨 minimal-matte Progress https://progress-bar.xyz/100/?style=minimal-matte

πŸ“‘ Progress from a JSON URL

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}/.


⚑ Caching

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.


πŸš€ Deployment

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.

🟣 Render

Deploy to Render

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 /health periodically, or using a paid instance type avoids that.
  • Custom domain on Cloudflare: add the domain in Render (Settings β†’ Custom Domains), create a CNAME pointing to <service>.onrender.com in 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

Deploy with Vercel

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.

🏠 Self-hosting (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)

1. Prerequisites

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 sh

2. Install

install.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 # TLS

Optional settings (cache TTLs, gunicorn workers/threads, logging) go in deploy/env β€” copy deploy/env.example.

3. Verify

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 call

4. Update

cd /opt/progressbar/app && deploy/update.sh

update.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.

Without Docker

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.

Behind Cloudflare

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.

πŸ” security.txt

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.


🀝 Contributing

Check out CONTRIBUTING.md to learn how to contribute!

πŸ‘₯ Contributors

guibranco
Guilherme Branco Stracini
nimble-turtle
nimble-turtle
ztest95
ztest95
Pointbr8ker-123
David Nwosu
EduardoBaptista01
Eduardo Baptista
bhosley
bhosley

πŸ€– Bots

dependabot[bot]
dependabot[bot]
github-actions[bot]
github-actions[bot]
penify-dev[bot]
penify-dev[bot]
deepsource-autofix[bot]
deepsource-autofix[bot]
snyk-bot
Snyk bot

πŸ“œ License

This project is licensed under the MIT License.

πŸ“„ See LICENSE for details.

About

πŸš€πŸ“Š Generates a dynamic progress bar image in SVG format, perfect for badges, dashboards, and visual indicators. Customize colors, sizes, and progress values with ease!

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

106 stars

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages