getBible API

One script that deploys and maintains every public getBible API domain on a server, securely and at high volume. A domain is a host name with one vhost and TLS at its selected terminator; its endpoints are its version folders (/v2/, /v3/), or the domain root itself when it has none.

The project and public API documentation website is getBible.net. The MCP usage guide describes the official MCP service at https://mcp.getbible.net/.

• Static domains: each endpoint a tree of JSON, checksum and text files copied faithfully from its own trusted git repository with its own deploy key. Endpoints share their domain's isolated sync user and nginx vhost; each tree is published as atomic hard-linked releases and served by nginx with open CORS, locked security headers, problem-document errors and compression.
• Runtime domains: the query (references to verses) and search (full-text search) services built on the getBible librarian, one service per version behind the one vhost, each an immutable release run by gunicorn as a sandboxed user behind a separate systemd socket for each deployment. Candidates pass readiness before nginx switches traffic; old workers drain before their backend stops. The versions a kind can serve are declared by its implementations under src/apps/, never by the tool.
• MCP domains: deploy the installable getbible-mcp Python library as its own service on a configurable domain, such as https://mcp.example.org/. One root protocol endpoint covers every supported upstream API version; select those versions in tool arguments. Its MCP traffic dashboard view reports protocol/tool activity and client details separately from query and search. See MCP setup, updates and rollback for native/Docker configuration.
• Static and query/search pages and OpenAPI: each versioned endpoint has a documentation page at /vN/ and an OpenAPI address at /vN/openapi.json, the domain page at / lists its endpoints, versions.json maps them to their documents, and the getBible icons in img/ (favicon and page logo) serve every domain unless replaced. Each is generated by the tool, taken over by the operator (edited in place, never rewritten again), or, for static endpoints, taken straight from the repository. Static builders supply their contracts; runtime contracts are generated here. Discovery includes a single root endpoint and refreshes automatically as endpoints and files change.
• Access modes per domain: open, metered (public budget per address, token holders unlimited) or token only, with bearer tokens issued from the menu.
• Operations: JSON logs of everything, size-based rotation with retention, analytics with total calls and unique callers, Telegram notifications for every change, Cloudflare integration, manager updates from the menu or one command, application updates and generation rollback.
• Staged deployments: a domain can be installed and verified on a server its DNS does not point to yet, with a placeholder certificate in managed TLS mode or the HTTP origin in external TLS mode, and no automatic public change; Go live later takes it over one domain at a time (certificate, Cloudflare DNS, HTTPS). Stage again suspends automatic public DNS changes while keeping the deployment available. In native managed TLS, certificates come from Let's Encrypt over HTTP-01 or, with the stored Cloudflare token, DNS-01 before any DNS change. With external TLS, HAProxy owns certificate issuance and renewal. New domains can be checked before public launch.

Query and search API versions

Manager release 3.0.0 supports v2 and v3 for both runtime kinds. Select the version in the CLI, terminal menu or dashboard, and point it at the local data root containing that version's folder. A v3 endpoint reads v3/; an existing v2 endpoint continues reading v2/. Both can run on the same domain.

After the static v3 endpoint has been synced, add v3 to existing runtime domains:

sudo ./getbible.sh version add query.getbible.net v3 --repository /srv/getbible/api.getbible.net --yes
sudo ./getbible.sh version add search.getbible.net v3 --repository /srv/getbible/api.getbible.net --yes

The librarian retains v3 verse metadata, including word tokens, spans and paragraph markers, inside the existing query and search response envelopes. See runtime setup and response contracts and the v3 source OpenAPI.

MCP domain

Consumer documentation is at getBible.net/mcp. The official client endpoint is https://mcp.getbible.net/; this engine can deploy the same service on any operator-configured domain.

Deploy MCP on its own domain:

sudo getbible deploy mcp --domain mcp.example.org --python 3.12

MCP clients connect to https://mcp.example.org/. The root path speaks the MCP protocol; it has no API-version folder or additional endpoint suffix. The engine manages the domain, Python environment, service, updates and rollback while the PyPI library provides the MCP capabilities. See MCP domain setup for the package prerequisite and configuration.

Choose native or Docker deployment

The Docker deployment pulls the prebuilt image from GitHub Container Registry. It runs systemd, nginx, static synchronization, query/search and the existing management menu in one container. Multiple domains share one HTTP port behind OPNsense HAProxy and Cloudflare; HAProxy owns external TLS. The host needs only compose.yaml and the settings described in Docker deployment, not a repository clone or local build.

After one-time registry authentication and configuration:

docker compose pull
docker compose up -d
docker exec -it --user root <container-name> getbible

Replace <container-name> with the name shown by docker ps. That command opens the menu. For a command shell, use:

docker exec -it --user root <container-name> /bin/bash

Inside the root shell, run getbible commands directly without sudo, for example getbible dashboard update or getbible dashboard status. Use exit to return to the Docker host before running Docker image/Compose commands.

A replacement image automatically refreshes the dashboard, telemetry and enabled endpoints after restoring the saved services. Runtime candidates use bundled dependencies and replace the serving generation only after readiness succeeds. getbible status shows the image release, applied release and update state; getbible update retries or reapplies it. Restarting an already applied image skips this refresh. Bible source data, DNS and certificates remain unchanged.

getbible is a real executable command linked to the same manager. Add its existing arguments to run any action directly, for example docker compose exec --user root getbible getbible list. Persistent data lives under one host directory with recorded service-account identities. Native deployment remains available with the workflow below. The reasons for both paths and the public-cache policy are recorded in Deployment decisions.

Native deployment

Install as root over SSH with a read-only deploy key for this manager repository, so that key serves every later manager update. Static endpoints get separate keys for their data repositories (root's key and SSH configuration are set up once, see Installing on a server):

sudo git clone git@github.com:getbible/api.git /opt/getbible/api
cd /opt/getbible/api
sudo ./getbible.sh install-deps
sudo ./getbible.sh

When improvements are published, update the manager with one command, or choose Update manager script in the menu:

sudo ./getbible.sh self-update

This fetches the clone's upstream with root's manager key and fast-forwards the checkout; the next invocation runs the updated code. Hosted domains change only when you separately apply the checkout, for example with sudo ./getbible.sh update [DOMAIN]. See Updating and recovery.

Ubuntu 24.04 and 26.04 are the deployment targets. The manager detects the OS, architecture and capabilities; Debian/Ubuntu prerequisites use apt. Other glibc Linux hosts need compatible tools, systemd and nginx installed with their package manager. Managed runtimes cover x86_64 and aarch64 with glibc 2.28 or newer.

Runtime CPython is installed under /opt/getbible/python from a reviewed, SHA-256-verified catalog covering Python 3.12, 3.13 and 3.14. Interpreter, standard library and virtual environments belong to the application, so distro Python updates do not replace them. Updates are explicit:

sudo ./getbible.sh list
sudo ./getbible.sh runtime versions
sudo ./getbible.sh update query.getbible.net
sudo ./getbible.sh runtime query.getbible.net update --python 3.14
sudo ./getbible.sh runtime query.getbible.net v2 rollback

Ordinary update applies reviewed application/package changes while retaining each endpoint's exact Python patch. Explicit runtime ... update adopts the catalog's latest patch in the selected family. Allow memory for both runtime generations during upgrades. The kernel, glibc, nginx and systemd remain host dependencies; plan their maintenance separately.

Documentation:

Document	Contents
docs/DOCKER.md	prebuilt image, Compose, configuration, commands, persistence and recovery
docs/REGISTRY_ACCESS.md	package read token, one-time Docker login, production pulls and token rotation
docs/OPNSENSE_HAPROXY.md	OPNsense setup order, backend form fields, automatic client-IP recognition, direct access, IPv4 origins and verification
docs/DEPLOYMENT_DECISIONS.md	objectives, constraints and reasons for deployment and caching behavior
docs/INSTALL.md	first setup, where things live
docs/NEW_SERVER.md	fresh server setup: endpoint keys, staged domains, go-live and maintenance
docs/STATIC_ENDPOINTS.md	static domains: endpoints, synchronisation, serving
docs/RUNTIME_ENDPOINTS.md	runtime domains: the query and search services, one service per version
docs/MCP.md	a dedicated MCP domain: root protocol endpoint, local upstreams, package updates and rollback
docs/RUNTIME_RESOURCES.md	automatic resource allocation, memory retention and translation warm-up
docs/DASHBOARD.md	private dashboard, Telegram sign-in, live reports and administrative operations
docs/PAGES.md	documentation pages, OpenAPI documents, icons (favicon, logo), versions.json
docs/ACCESS_MODES.md	open, metered, token; budgets; tokens
docs/LOGGING.md	logs, rotation, analytics
docs/TELEGRAM.md	notifications
docs/CLOUDFLARE.md	proxy modes, rules, real IP, origin pulls
docs/UPDATING.md	updating and rolling back
docs/ADDING_A_RUNTIME_KIND.md	the contract for a new runtime service or a new version of one
docs/SECURITY.md, docs/ARCHITECTURE.md	how it is put together

Every menu action has a command line form: ./getbible.sh --help. Tests: tests/run.sh (lint, unit, command line) and tests/run.sh --all (plus real nginx, gunicorn and SSH authentication; needs nginx, openssh-server and root).

License: Apache 2.0.