OpenGeoMetadata API Mirror Network

Shared infrastructure that becomes stronger with every new member

Document control

Executive summary

Companion document: Technical Implementation Guide
Download: Two-page Executive Brief (PDF)

OpenGeoMetadata has already solved the hardest community problems: a shared discovery schema in OGM Aardvark, a distributed and transparent way to steward metadata in GitHub, a proven API platform for harvesting and serving those records, and the configurable OGM Discovery (ogm-discovery) frontend that can be branded for an institution and hosted as a static site on GitHub Pages.

The next step is to make delivery as collaborative as the metadata.

The OpenGeoMetadata API Mirror Network would place a protected, health-aware global endpoint in front of multiple institutional deployments of the OGM API. A mirror-host institution would contribute one ordinary Linux virtual machine and a technical contact. The OGM service operator would deploy and maintain the containerized API stack with Kamal, keep the mirror synchronized with the public OGM Aardvark repositories, monitor its readiness, and add it to the shared traffic pool.

Every OGM Discovery site would use the same stable network API endpoint. Its theme would present the adopting institution's brand and, when desired, scope search results to that institution by default. The underlying API would still expose the shared OGM corpus, enabling broader discovery and reuse.

This produces an unusually favorable exchange:

An institution contributes the equivalent of one modest server and gains the foundation for a customizable, institution-branded geospatial discovery platform backed by the combined capacity and resilience of the OpenGeoMetadata community.

Crucially, capacity contribution and service adoption do not have to be one-to-one. Institutions able to contribute a VM create shared headroom not only for their own discovery sites, but also for smaller libraries that cannot provide server infrastructure. A service-only adopter can publish Aardvark metadata in GitHub, customize and brand OGM Discovery, and use the shared OGM API endpoint without provisioning, securing, patching, or monitoring a local backend. Its participation requires metadata stewardship and site customization, not a campus application-hosting project.

That makes each contributed mirror a community multiplier. It expands service capacity for current members, opens a nearly infrastructure-free path for new members, and brings more institutions and collections into shared discovery. The institutions with capacity lift the operating burden; the institutions without capacity enrich the network's metadata, reach, and public value.

Growth no longer concentrates traffic and risk on one campus. Each new adopter can strengthen the network through infrastructure, metadata, community reach, or some combination of the three. Each new mirror makes the network harder to overwhelm, less dependent on any single institution, and more useful to every member. It also gives every mirror host a safe maintenance window: a local node can be drained for operating-system or application upgrades while its discovery site continues using the remaining network.

The proposal

Create a shared public read endpoint for OGM services, backed by a federation of compatible API mirrors hosted by participating institutions.

1. OpenGeoMetadata repositories remain the canonical source. Institutions continue publishing public Aardvark records through the existing GitHub model. No institution gives up ownership or control of its metadata.
2. Each mirror serves the full public corpus. A mirror independently harvests and indexes the same OGM repositories using webhook events and scheduled reconciliation. The nodes do not need cross-campus database replication.
3. A protected global edge manages public traffic. A stable hostname applies caching where appropriate, rate limits and bot controls, checks each origin's health and data freshness, and routes requests by capacity and availability. A node can be taken out of rotation for planned maintenance without changing the public URL.
4. OGM Discovery provides the institutional experience. The static frontend runs on GitHub Pages, carries local branding and content in configuration, and queries the shared network endpoint. The frontend requires no local application server or mirror VM.
5. Kamal makes operations repeatable. The OGM operator deploys the same versioned container release to every mirror, stages upgrades, checks compatibility, and can roll back quickly.

The public edge should load balance only the read-oriented API surface. Admin, harvest, deployment, and other privileged operations remain off the shared public route. An origin is eligible for traffic only when its application version, search services, record freshness, and capacity checks pass.

Why directors should support it

One contribution produces six returns

• A public service without a local software project. The institution gains a production-grade discovery backend and the foundation for a customizable, institution-branded frontend without assembling its own development team.
• An inclusive path for institutions without infrastructure. Mirror capacity is a pooled community contribution, not a condition of membership. A small library can adopt the shared backend, publish its metadata, and launch a branded discovery site without operating a VM or maintaining an API stack.
• Protection against traffic spikes and abusive automation. Edge controls absorb or reject unwanted traffic before it reaches campus systems, while healthy origins share legitimate requests.
• Continuity through institutional outages. Maintenance, network incidents, or a failed mirror do not require users to change URLs. Traffic moves to the remaining healthy nodes. Local teams gain time to patch, upgrade, test, and return their node to service without creating a public outage.
• Shared improvements without repeated procurement. New API capabilities, accessibility work, performance improvements, and frontend features can move through one common release path.
• Visible participation in community infrastructure. Mirror sponsors contribute durable capacity; service-only adopters contribute metadata, expertise, and reach. Both forms of participation benefit researchers and libraries across the network.

The scaling model is the strategic advantage

A centralized service becomes more expensive and more fragile as adoption grows. The mirror network reverses that relationship:

new mirror host -> more shared capacity -> room for both mirror hosts and service-only adopters -> broader discovery and stronger service -> easier next adoption

The result is cooperative infrastructure with horizontal capacity, geographic diversity, and organizational redundancy. No single library has to provision for the whole community's peak traffic, and no single campus becomes the permanent point of failure.

Two participation paths, one community service

Hardware is a valuable contribution, not an admission requirement.

An institution may begin as a service-only adopter and contribute a mirror later, or host capacity before launching its own frontend. Governance should recognize both as meaningful participation: one supplies shared infrastructure; the other broadens the corpus, community, and impact that infrastructure serves.

What a mirror host contributes and gains

The intended division is simple: the institution hosts the machine; the OGM network operates the application.

Cost and effort

Reference mirror profile

The current BTAA production deployment is already a single-host Kamal design. Its published production resource envelope reserves up to 8 CPUs and about 5 GB for the web role, 1.75 CPUs and 2 GB for the worker, a 4 GB Elasticsearch heap, and a Redis ceiling of 12 GB, in addition to PostgreSQL, Docker, filesystem cache, and the operating system.

A conservative reference mirror therefore is:

This is deliberately ordinary infrastructure. As an August 2026 external price benchmark, a Hetzner AX42-class dedicated server provides 8 physical cores / 16 threads, 64 GB RAM, two 512 GB NVMe drives, and a 1 Gbps connection for about $117 per month before IPv4, tax, and setup. That is approximately $1,405 per year. Limited inventory can be lower.

A campus VM from existing capacity may have little or no incremental cost.

A service-only adopter has no OGM API server cost. It uses capacity already contributed to the network and needs no campus VM or local backend deployment. Its effort is focused on metadata, OGM Discovery customization, and community participation.

For budgeting, use $1,500 per year per mirror node as the target infrastructure contribution, with local chargeback replacing the external benchmark when applicable. This is not a procurement quote. A mainstream public-cloud VM can cost materially more; the design does not require one.

The global edge, DNS, and shared monitoring are network-level costs rather than per-institution costs. At pilot scale they should be budgeted centrally and are expected to be small compared with even one local software implementation.

Target mirror-host effort

• One time: 4-8 staff hours to provision the VM, establish DNS/firewall rules, confirm SSH access, and name contacts.
• Ongoing: at most a few host-support hours per quarter for OS maintenance, capacity changes, and campus networking. Application releases and routine data operations are handled centrally.
• No local frontend server: OGM Discovery builds and publishes through GitHub Pages.

For a service-only adopter, the VM, firewall, SSH, operating-system, and backend support tasks disappear. The institution can participate without a local IT deployment; only optional campus policies such as a custom domain may call for local coordination.

These are pilot targets to validate, not contractual service levels.

Alternatives considered

The recommended model is the only option considered that simultaneously grows capacity with participation, preserves institutional hosting, and removes the backend infrastructure requirement for smaller adopters.

Open questions for community review

The draft deliberately leaves policy choices open where community authority is required:

• Which OGM group will sponsor the proposal, and which body can authorize the pilot and any later production service?
• Who will fund and operate the global edge, DNS, shared monitoring, and incident coordination?
• What fair-use policy, capacity threshold, and onboarding criteria should apply to mirror hosts and service-only adopters?
• What service objectives, support boundaries, security expectations, and incident authority should the operating compact define?
• How should a mirror be retired, replaced, or temporarily removed from the network?
• Should the community adopt the proposed CC BY 4.0 document license?

Draft review and decision process

Comments should be recorded in the repository's GitHub issue tracker. Before a formal review period begins, the sponsoring group should designate one issue or discussion as the canonical review thread, name the decision authority, and publish a closing date. The proposal lead will publish numbered 0.x revisions and summarize material changes there. A pilot decision and its rationale should be recorded publicly in this repository.

Proposed lifecycle:

Community Discussion Draft -> Pilot Candidate -> Approved Pilot -> Production Proposal -> Accepted, Rejected, Withdrawn, or Superseded

Revision history

Approval record

No approval has been recorded. Version 0.1.0 is a discussion document and does not establish an OGM roadmap, service commitment, or technical standard.

Operating safeguards

The network should launch with a short operating compact:

• Version discipline: mirrors run a supported, pinned OGM API release. Upgrades are staged, canaried, and reversible.
• Maintenance without service interruption: an institution can drain its mirror, complete OS or OGM API work on its own schedule, and rejoin only after readiness and freshness checks pass. Its public discovery site continues through other healthy mirrors.
• Readiness, not simple uptime: the edge checks API compatibility, search health, data freshness, and capacity before admitting a mirror to rotation.
• Weighted participation: traffic weights reflect each institution's stated capacity; a smaller node is still valuable and is not overloaded for the sake of even distribution.
• Origin protection: mirror addresses are not advertised as the primary public service. Firewalls should accept application traffic from the edge and restrict administrative access.
• Rebuildable nodes: GitHub Aardvark repositories remain canonical. Search indexes, caches, and public read databases are derived state that can be rebuilt, reducing backup complexity and vendor lock-in.
• Transparent status: members can see mirror health, software version, corpus freshness, and current traffic weight.
• Clear responsibility: OGM owns application operations and routing; mirror hosts own VM, OS, and campus network availability; service-only adopters have no backend host responsibility; the community owns schema and service policy.

Recommended pilot

Authorize a 90-day, three-node pilot using the current BTAA node plus two additional institutional mirror hosts. The pilot should also onboard at least one service-only adopter that contributes no VM, proving that shared capacity can remove the local backend IT requirement.

The pilot should prove six things:

1. A new institution can be provisioned with no local application development.
2. All mirrors serve a compatible API and sufficiently fresh corpus.
3. Loss of one node - or a planned node drain for an upgrade - causes no user-visible URL change and no manual intervention.
4. Bot controls and rate limits protect origins while legitimate traffic is distributed by health and capacity.
5. Aggregate tested capacity increases when a mirror joins the pool, while the measured institutional support burden remains within the target.
6. A service-only adopter can publish metadata and launch a customized discovery experience without provisioning or operating backend infrastructure.

At the end of the pilot, publish the measured onboarding time, operating effort, cost, traffic distribution, failover result, and metadata freshness. Those results become the evidence and onboarding package for the next institution.

Decision requested

Approve the OpenGeoMetadata API Mirror Network as a shared-infrastructure pilot; authorize a three-node implementation and a service-only adoption path; designate appropriate service and technical contacts for each participation mode; and charge the OGM working group with returning a production governance and service-level proposal based on measured results.

The community has already created the schema, the metadata network, the API, and the low-maintenance frontend. The mirror network is the piece that turns those assets into durable, community-scale infrastructure.

Foundations and planning sources

• OpenGeoMetadata
• OpenGeoMetadata repositories on GitHub
• BTAA Geospatial API
• OpenGeoMetadata API
• OGM Discovery (ogm-discovery)
• BTAA production Kamal configuration
• Hetzner AX42 hardware and June 2026 pricing
• Cloudflare load balancing and health-aware routing