Repository navigation
Host OpenBridge
This page helps an organization put OpenBridge on its own web address so clients and staff can use it in a browser. It is for whoever runs your website or IT, working with program staff. The detailed, step-by-step sources are the hosting guide (also inside the download) and deployment notes.
OpenBridge is a prototype. The rules are drafts that experts have not verified, and no legal review has happened yet. Do not present it as an official or verified tool. Tell your users that results are estimates.
OpenBridge is a set of static files: a web page, scripts, and rule data. There is no database and no backend. All screening happens in each person's browser, so no personal data ever reaches your server.
- Download
openbridge-hosted-v<version>.tar.gzfrom the repository's Releases page. It holds the app insite/, plusDockerfile,compose.yaml,nginx.conf,Caddyfile,serve.mjs, andBUILD-INFO.json. Container users can instead downloadopenbridge-image-v<version>-linux-amd64.tar.gzor-linux-arm64.tar.gz. - If no release is published yet, you can build the same files from source. See Developer setup and releasing.
- Optional: check your download against
SHA256SUMS.txtfrom the same release. - A domain name and a way to serve it over HTTPS.
-
Try it on one computer. In the unpacked folder, run
node serve.mjs(needs Node.js 22 or newer) and open http://127.0.0.1:8080. Only that computer can reach it. - Choose how to serve it. Pick one option from the table below.
-
Set your defaults in
site/deployment-config.json(see below). - Turn on HTTPS. Always serve the public site over HTTPS. Offline use and installing the app on a phone both need it.
- Go through the privacy checklist below before you share the address.
| Option | Good for | How |
|---|---|---|
| Static host or CDN | Most organizations | Upload the contents of site/. Turn on single-page app fallback so unknown paths serve index.html. |
| Docker or Compose | Teams that use containers |
docker compose up -d. It listens on 127.0.0.1:8080; put an HTTPS reverse proxy in front. |
| Caddy | Easiest HTTPS on your own server | Copy site/ to /var/www/openbridge, set your domain in Caddyfile, run caddy run --config Caddyfile. |
| nginx | Servers that already run nginx | Copy site/ to /var/www/openbridge, adapt nginx.conf, and add your certificates. |
serve.mjs |
Simple setups behind a proxy |
HOST=127.0.0.1 PORT=8080 node serve.mjs, then point your HTTPS reverse proxy at it. |
The container runs nginx as a non-root user on port 8080, keeps no access log, and answers health
checks at /healthz. Only set HOST=0.0.0.0 for serve.mjs if you understand that other machines
can then reach it directly, without HTTPS.
Edit site/deployment-config.json. The app reads it each time it starts. With Compose you can mount
the file instead of rebuilding (see the comment in compose.yaml).
{
"defaultMode": "navigator",
"autoClearTimeoutSeconds": 300
}-
defaultMode:individualfor public kiosks and personal use, ornavigatorfor staff who screen several clients. See Guide for navigators. -
autoClearTimeoutSeconds: seconds of no activity before the screen clears itself, in individual mode. The default is 180 (3 minutes). Use a short time on public computers.
Include both fields. If either is missing, the app ignores the file and uses its defaults. The
file also accepts orgName, contact, and localResources, but the app does not show them yet.
- Do not add analytics, tracking pixels, chat widgets, or any third-party scripts.
- Turn off access logs, or keep them small and short-lived. The app never puts personal details in web addresses, but logs are still data you must protect.
- Keep the security headers from the example configurations. They block outside scripts.
- Do not put a login or form in front of the app that collects personal details.
- On public computers, keep
defaultModeasindividualso the auto-clear stays on.
There are no automatic updates. When a new release comes out:
- Download the new hosted file.
- Replace the contents of
site/, keeping your owndeployment-config.json. - Check
BUILD-INFO.jsonfor the version, the rules data version, and each state's review status.
People get the new version the next time they open the app. Rule values change every year, so plan to update at least once a year. Watch the repository's releases to hear about new versions.
OpenBridge uses the GNU Affero General Public License v3.0. If you change it and offer it to others over a network, you must share your changes.
OpenBridge is a prototype. Its rules are drafts that experts have not verified yet, and results are
estimates, not decisions. It is not legal advice. Need help applying for benefits? Call 211 or visit
211.org. This wiki is edited in the wiki/ folder of the repository.
Questions: openbridge@starlingtek.com.
Start here
Use OpenBridge
- Using OpenBridge
- Understanding your results
- Guide for navigators
- Privacy and your data
- Run it on your computer
- Host it for others
- Use it with an AI assistant
Help without code
- Ways to help
- Review rules as an expert
- Record a test case
- Report a rule problem
- Translate OpenBridge
- Test accessibility
- Community rule toolkit
Rules and policy (with code)
- How the rules engine works
- State adapters
- Add or change a rule
- Add a new state
- Golden test cases
- Yearly data updates
Developers