Field notes · leaflet

Building a static civic map with no server and no bill

How I shipped a public city map as a static site: Leaflet, committed GeoJSON, and GitHub Pages, for zero dollars a month and almost no attack surface.

·8 min read

Someone wants a public map. Parks, facilities, snow routes, whatever it is, the request is always “put it on the website so residents can see it.” The obvious paths all carry a recurring cost or a server to babysit: a mapping-platform subscription, per-seat GIS licenses, a hosted database, a basemap bill that scales with traffic. For a one-person shop, every one of those is a liability you signed up to maintain forever.

I built ours as a static civic map instead: a plain Leaflet page reading GeoJSON committed to the repository, served from GitHub Pages. There is no server at runtime. It costs nothing per month, it cannot be SQL-injected because there is no SQL, and it has stayed up without my attention for longer than anything else I run. Here is how, and the three things that actually tripped me up.

Key takeaways

  • A static map has no runtime server: the browser loads a Leaflet page plus committed GeoJSON, so hosting is free and the attack surface is nearly nothing.
  • Verify the basemap license before you wire it in. Several popular free tiles forbid public government use without a paid plan.
  • With no server there is nothing to proxy through, so a live third-party fetch only works if that endpoint sends CORS headers. Test with curl first.
  • Never reverse-geocode a user’s dropped pin through a third-party API. That ships their coordinates off-device. Do the address lookup on-device instead.

Why static instead of a mapping platform?

Because a static site removes the two things that actually cost you: a monthly bill and a server to secure. The map is just an HTML page, a little JavaScript, and data files. GitHub Pages serves it for free, a CDN caches it, and there is no database, no login, and no runtime code for anyone to attack. A small shop can run it for years without touching it.

The three routes I compared, with the tradeoff that decided it:

Approach Monthly cost What you maintain
Hosted mapping platform Subscription, often per-seat An account and a renewal you cannot skip
Your own server plus database Hosting plus patching A box, a DB, and every CVE that lands on them
Static site (Leaflet plus GeoJSON) Zero A repository, and a plan to keep the data fresh

The static column is not free of work. It moves the work from operating a system to curating data, which is a much better trade for a lean team. The catch is in that last cell: because the map only shows what is committed, you have to decide up front how the data stays current. More on that below.

What does the map actually load?

A Leaflet map and one or more GeoJSON files you committed to the repo. Leaflet is a small, dependency-free mapping library that renders tiles and vector layers in the browser. You give it a basemap for context and a GeoJSON layer for your features, and it draws them. The entire “backend” is static files on a CDN.

// Initialize the map and a legal basemap (see the licensing note below).
const map = L.map('map').setView([43.0, -83.6], 12);

L.tileLayer('https://{s}.example-public-imagery/{z}/{x}/{y}.png', {
  attribution: 'Imagery: your state GIS program',
  maxZoom: 19,
}).addTo(map);

// Load a committed GeoJSON layer: parks, facilities, whatever the request was.
fetch('/data/facilities.geojson')
  .then((r) => r.json())
  .then((geojson) => {
    L.geoJSON(geojson, {
      onEachFeature: (feature, layer) => {
        layer.bindPopup(feature.properties.name);
      },
    }).addTo(map);
  });

That is the whole shape of it. Everything else is styling, more layers, and a legend. The data lives at /data/*.geojson in the repo, so updating the map is a commit, and deploying is a push.

How do you get a basemap you are allowed to use?

Carefully, because this is the trap I fell into first. I wired up a good-looking free basemap, shipped a demo, and only then read the terms. The free tier forbade public government use without a paid plan. The map looked perfect and was quietly out of compliance. I had to rip the tiles out and start over.

Verify the tile license before you wire it in. The safe sources for a public civic map are usually the ones your government already has rights to: your state’s public GIS imagery service, your own organization’s map tiles if you run ArcGIS, or an openly licensed set like OpenStreetMap with proper attribution. Whatever you pick, honor the attribution the license requires, and keep a note of which service and which terms, so the next person does not have to re-litigate it.

Can the map pull live data if there is no server?

Only if the data source lets the browser call it directly, which many do not. A static site has no server to proxy a request through, so a client-side fetch of a third-party dataset only works when that endpoint sends the right CORS headers. If it does not, the browser hard-blocks the call and your layer silently never loads.

Test it before you design around it:

# Look for an Access-Control-Allow-Origin header in the response.
curl -I -H "Origin: https://yourmap.example.gov" https://some-data-endpoint/...

If the header is there, you can fetch live and always show current data. If it is missing, do the fetch at build time instead: a scheduled job pulls the data, writes a GeoJSON file, and commits it, so the committed copy is what ships. I use that same build-time-fetch instinct that keeps my reads against vendor systems read-only and predictable: pull deliberately, commit the result, and the live site never depends on someone else’s uptime.

How do you avoid leaking residents’ data?

Two ways, because a map is a privacy surface whether you meant it to be or not. The first is about the user. I wanted a “click the map and see the nearest address” feature and nearly wired it to a geocoding API. Then it hit me: every click would send the resident’s chosen coordinates to a third party. On a public civic site, that is exactly the kind of quiet tracking you do not want to own.

So the address lookup happens on-device. I commit a compact lookup table of [lat, lng, address] built from open parcel data, load it lazily on the first click, and find the nearest point with plain distance math in the browser. No third-party call, nothing leaves the device, and it works offline. The second privacy rule is about the data you publish: before you commit any layer, check it for home addresses or personal details. A parcels or business layer can expose where people live. Filter it, aggregate it, or leave it off.

How does the data stay current without a GIS person?

This is the real design problem with a static map, and it is worth solving before launch, not after. Because the site reads committed files, every update has to reach the repository somehow, and the person with the new data usually does not use Git. If you skip this, the map is accurate on launch day and slowly rots.

The pattern that works: give the non-developer a form or a list they already know how to edit, and automate the commit behind it. A staffer edits a shared list, an automation validates the entries and writes the updated GeoJSON back to the repo, and the push redeploys the site. The validation step is not optional, because a commit to the main branch goes live with no human in between. Decouple the map from the pipeline: ship the map reading static files first, then layer the data-entry flow on afterward. The map does not care how the file got there.

What broke, and what I would tell past me

Three things, and all three were about the boundaries of “static,” not bugs in the code. The basemap license was the first, and the lesson was to read the terms before falling in love with the tiles. The CORS wall was the second: I assumed I could always fetch fresh data in the browser, and half the useful endpoints said no. The privacy near-miss was the third, and the one I am most glad I caught.

If I were starting over, I would write down the data-refresh plan on day one, next to the first commit. The map itself takes an afternoon. Keeping it honest and current for years is the actual project, and it is a content problem, not a code problem. Static hosting gave me a site that cannot fall over. It did not give me a site that stays true on its own, and that part is on me.

When a civic tool genuinely does need a backend, I do not bolt one onto the map. I build it separately, the way I run small internal apps on the server I already have, and keep the public map exactly as boring and bulletproof as static hosting makes it.

FAQ

Do I need a server to host a public map?

No. A Leaflet page plus committed GeoJSON served from GitHub Pages or any static host needs no server at runtime, costs nothing, and has almost no attack surface. You only need a backend for features that genuinely require one, like accepting submissions, and even then you keep it separate from the map.

Can I use any basemap for a government map?

No. Several popular free basemap tiers forbid public or government use without a paid plan, so verify the license before wiring the tiles in. Safe options are usually your state’s public GIS imagery, your own ArcGIS tiles, or OpenStreetMap with the required attribution.

How do I keep the map’s data up to date?

Automate the path from a form or list the data owner already uses to a validated commit of the GeoJSON. Because the site reads committed files, an update only appears after it reaches the repo, so the update flow, with a validation gate, is the part to design first.

Why not just reverse-geocode a clicked point with an API?

Because that sends the user’s coordinates to a third party on every click, which is quiet tracking you should not put on a public civic site. Commit a small address lookup table built from open data and do the nearest-point search on-device instead. It is private, offline-capable, and license-clean.