docker-staticmaps

Open-source static map generation, honestly reviewed. For developers tired of Google’s per-request billing.

TL;DR

• What it is: A self-hosted REST API that generates static map images — PNG snapshots of maps with markers, lines, polygons, and circles — deployed as a single Docker container [README].
• Who it’s for: Developers who need map thumbnails for blogs, property listings, trip summaries, or dashboards and don’t want to pipe every image request through Google Maps or Mapbox [README].
• Cost savings: Google Maps Static API charges $2.00 per 1,000 requests after a 28,500/month free tier. Mapbox charges $0.50 per 1,000 after 50,000 free. A self-hosted instance on a $5–6/mo VPS costs nothing per request.
• Key strength: One docker run command and you have a caching, rate-limited map API that supports OpenStreetMap, Esri, Stamen, Carto, and any custom tile server [README].
• Key weakness: Small project — 122 stars, 7 forks, single maintainer. AGPL-3.0 license creates complications for embedding in commercial products. No managed SaaS fallback if your self-hosted instance goes down.

---

What is docker-staticmaps

docker-staticmaps is a lightweight REST API that renders static map images on demand. You send it an HTTP request with parameters — center coordinates, zoom level, image dimensions, basemap provider, and optional overlays — and it returns a PNG. That’s the whole product.

The project is built in TypeScript (95.8% of the codebase), wraps the existing staticmaps npm library by Stephan Georg (which handles the actual tile fetching and image composition), and adds the REST API layer, Docker packaging, tile caching, image caching, and rate limiting on top [README]. The maintainer is Max Dietrich (mxdcodes), a single developer who has shipped 12 releases, the latest being v0.9.2 in March 2026 [GitHub].

The use case is narrow and concrete: you need a map image embedded in a page, email, PDF, or app — and you want to generate it server-side without calling Google or Mapbox. Static maps show up constantly in property listings (“here’s where this apartment is”), fitness apps (“here’s your route from Saturday”), travel blogs (“here’s where we stayed”), and administrative dashboards that need geographic context without a full interactive map.

The project was featured in the selfh.st Self-Host Weekly newsletter, which covers new and updated self-hosted software [1] — a useful signal that it has at least landed on the radar of the self-hosting community, even if it hasn’t generated deep third-party reviews yet.

---

Why people choose it

There’s no shortage of third-party review articles for docker-staticmaps — because there aren’t any. This is a young, niche project with 122 stars and limited community discussion. What follows is an assessment based on the project itself and the problem it solves.

The Google Maps billing problem. The Google Maps Static API is the dominant option for generating map images. It works, it’s easy, and it has a generous free tier (28,500 requests/month). Then you grow. At 100,000 requests/month you’re paying $143/month. At 500,000 requests/month you’re paying roughly $943/month. These numbers aren’t hypothetical — they’re the published Google Maps Platform pricing. Every request that goes through Google costs money, and the meter runs whether you’re doing it in production or in a preview environment.

The Mapbox alternative has the same structure. Mapbox Static Images API starts cheaper ($0.50 per 1,000 after 50,000 free), but it’s still per-request SaaS billing. You’re renting the map.

The self-hosted proposition. With docker-staticmaps, you pay for the VPS — roughly $5–6/month on Hetzner or Contabo — and nothing per request. The tile data comes from OpenStreetMap (free, community-maintained) or other tile providers of your choosing. The image rendering happens on your server. There is no per-request bill [README].

This is particularly compelling if your use case generates map images that don’t change often (property locations, static route displays, coverage maps) — the built-in tile and image caching means your server isn’t regenerating the same map on every page view [README].

---

Features

Based on the README and project documentation:

Core map rendering:

• Static map images with configurable width, height, center, and zoom [README]
• Overlay support: markers, polygons, circles, polylines, and text labels [README]
• Multiple basemap providers out of the box: OpenStreetMap, Esri, Stamen, Carto [README]
• Custom tile server support — point it at any XYZ tile endpoint [README]

Performance and protection:

• Tile caching — fetched map tiles are cached locally, reducing repeat requests to upstream tile providers [README]
• Image caching — generated images are cached, so identical requests don’t trigger a full re-render [README]
• Built-in rate limiting per IP — protection against abuse without needing a separate reverse proxy rule [README]

Developer experience:

• Simple REST API — a single GET request with query parameters generates an image [README]
• Interactive playground at http://localhost:3000 — a browser UI for testing parameters before integrating [README]
• Docker-ready — single docker run command to start [README]
• Full documentation at https://dietrichmax.github.io/docker-staticmaps/

Sample request:

GET /api/staticmaps?width=1000&height=1000&center=-18.2871,147.6992&zoom=9&basemap=satellite

What it doesn’t do:

• No vector maps, no interactive tiles, no routing
• No authentication layer — if you expose this publicly, rate limiting is your only protection
• No managed cloud offering — self-hosted only
• No webhooks, no async processing — synchronous request/response only

---

Pricing: SaaS vs self-hosted math

Commercial alternatives (per-request billing):

Provider	Free tier	Per 1,000 requests after free
Google Maps Static API	28,500/month	$2.00
Mapbox Static Images API	50,000/month	$0.50
MapTiler Cloud	~50,000 tiles/month	Usage-based, varies

docker-staticmaps (self-hosted):

• Software: $0 (AGPL-3.0)
• VPS: $5–15/month depending on the provider and resources
• Tile data: $0 if using OpenStreetMap; varies if using a commercial tile provider

Concrete numbers for a mid-sized use case:

Suppose you’re running a property listing platform generating 200,000 map images per month. On Google Maps Static API that’s roughly $343/month (28,500 free + 171,500 × $2.00 per 1,000). On Mapbox that’s roughly $75/month. On docker-staticmaps running on a $10/month VPS with 4GB RAM: $10/month — and your tile source is OpenStreetMap, which is free.

Annual savings vs Google: roughly $3,996. Vs Mapbox: roughly $780. The math compresses dramatically at lower volumes (at 30,000 requests/month, Google’s free tier covers you entirely), but once you’re past the free tier consistently, the VPS pays for itself quickly.

One important caveat: if you use a commercial tile provider (Mapbox, MapTiler, Stadia) as your basemap source inside docker-staticmaps, you’re still paying for those tiles. The savings calculation only holds cleanly when you use OpenStreetMap tiles.

---

Deployment reality check

The README’s quick-start is genuinely quick:

docker run -p '3000:3000/tcp' mxdcodes/docker-staticmaps:latest

That’s it. The container starts, exposes port 3000, and you can hit the API immediately. There’s no database, no persistent state beyond the cache, no external dependencies to wire up.

What you actually need:

• A Linux VPS with 512MB–1GB RAM (map rendering is not memory-intensive for typical use)
• Docker installed
• Optional: a reverse proxy (Caddy or nginx) if you want HTTPS and a custom domain
• Optional: a custom tile server if you want fully offline operation

Practical complications:

The interactive playground (the browser UI at localhost:3000) is a thoughtful addition that lets you test parameters visually before writing integration code — that’s more polish than most single-developer utility projects have [README].

The AGPL-3.0 license deserves direct attention. AGPL-3.0 means that if you use this service in a commercial product and users interact with it over a network, you’re technically obligated to publish your modifications (if any) under AGPL-3.0. For most use cases — “I have a Docker container generating map images for my site” — this doesn’t matter because you’re not distributing or modifying the software. But if you’re embedding this in a commercial product you sell to clients, read the license carefully. The underlying staticmaps library is MIT-licensed; only the docker-staticmaps wrapper code is AGPL-3.0 [README].

The project has 12 releases but only 7 forks and a single maintainer. That’s a bus factor of 1. If Max Dietrich stops maintaining it, you’re on your own with a TypeScript codebase — which is forkable and readable, but the maintenance burden shifts to you. For a low-stakes internal tool, this is fine. For a revenue-critical production service generating maps for your product, budget time to fork and maintain it yourself if needed.

There’s no authentication built into the API. If you expose this service on a public IP, the rate limiting per IP provides some protection, but it’s not a substitute for proper auth. Put a reverse proxy with auth in front of it if the service is accessible outside your internal network.

Tile caching and image caching are described in the README but not quantified — there’s no documentation on cache TTLs, cache size limits, or eviction policies [README]. In practice you’ll need to observe your disk usage and potentially configure cache limits depending on how many unique map requests you generate.

---

Pros and cons

Pros

• One-command deployment. docker run and it works. Genuinely no-friction startup — no database, no config file required for basic operation [README].
• Built-in caching and rate limiting. Most self-hosted tools make you add these yourself via nginx or middleware. Having them baked in reduces ops surface [README].
• Multiple basemap providers. OSM, Esri, Stamen, Carto, and custom tile servers — you’re not locked to one data source [README].
• Overlay support. Markers, polygons, circles, polylines, and text mean you can annotate maps, not just center them [README].
• Interactive playground. The built-in browser UI for parameter testing is unusually polished for a utility of this size [README].
• No per-request billing. The fundamental value proposition: pay for compute once, serve unlimited map images [README].
• Self-hostable docs. Documentation is versioned alongside the code and available offline [README].

Cons

• AGPL-3.0 license. More restrictive than MIT. Read it if you’re embedding this in a commercial product [README].
• Single maintainer, small community. 122 stars, 7 forks as of this review. If development stops, you maintain it yourself [GitHub].
• No authentication. The API is open by default. You’ll need to add auth via a reverse proxy for any public-facing deployment [README].
• No managed cloud option. If you don’t want to self-host, there’s no docker-staticmaps-as-a-service to fall back to.
• Cache behavior undocumented. Caching exists but TTLs, size limits, and eviction policy aren’t described in the README [README].
• Wrapper project. The core rendering logic is the upstream staticmaps npm library. Any limitations in that library carry through [README].
• No third-party reviews. Limited community discussion means fewer collective troubleshooting resources. You’re relying on GitHub issues and the docs.

---

Who should use this / who shouldn’t

Use docker-staticmaps if:

• You generate enough map images to exceed Google Maps’ or Mapbox’s free tier and the monthly bill is annoying
• You need map images for internal tools, admin dashboards, email templates, or PDF reports where SaaS pricing doesn’t make sense
• You’re comfortable managing a Docker container and don’t need a managed service
• Your use case is simple: center, zoom, basemap, maybe some markers — nothing requiring interactive maps or complex vector styling
• Privacy matters and you don’t want user location data going through Google or Mapbox servers

Don’t use it if:

• You need interactive maps — this renders static PNGs, not interactive tile layers
• Your use case is well within the free tiers of Google Maps or Mapbox — no reason to add operational complexity
• You’re building a commercial product and need to carefully audit license obligations (AGPL-3.0 may require legal review)
• You need guaranteed uptime SLAs — a single-maintainer project on your own VPS has no SLA
• You need enterprise features: auth, multi-tenancy, usage analytics — none of that exists here

---

Alternatives worth considering

Commercial SaaS (simpler, costs more at scale):

• Google Maps Static API — most widely used, most documentation, most integrations. Free up to 28,500 requests/month, then $2.00/1,000.
• Mapbox Static Images API — cheaper per-request than Google, better styling options. Free up to 50,000 requests/month, then $0.50/1,000.
• MapTiler Cloud — OpenStreetMap-based commercial service, GDPR-friendly EU hosting option.

Open-source alternatives:

• staticmaps (npm) — the underlying library docker-staticmaps is built on. MIT-licensed, runs in-process in a Node.js app. If you’re already running Node.js, you might not need the Docker wrapper at all.
• MapServer / GeoServer — full-featured geospatial servers. Massively more powerful and massively more complex. Overkill unless you’re doing serious GIS work.
• Nominatim + tile server stack — if you want full offline maps including geocoding, you need a heavier stack. docker-staticmaps only handles image generation, not tile hosting or geocoding.

For most developers making the “do I need to pay Google for map images” decision, the realistic shortlist is: stay on Google/Mapbox free tier (if volume is low), Mapbox paid (if volume is medium and you want managed), or docker-staticmaps self-hosted (if volume is high enough that VPS costs less than the API bill).

---

Bottom line

docker-staticmaps solves one problem well: it gives you a REST API that turns geographic parameters into map images, runs in Docker, caches aggressively, and costs nothing per request. If you’ve started paying Google $50–$300/month for static map images, a $6 VPS and a one-line Docker command eliminates that bill. The trade is operational responsibility — you maintain the container, watch the cache, and handle the bus-factor risk of a single-maintainer project.

The honest caveat is that this is a young project with limited community validation. It’s built on a solid upstream library, it’s written in readable TypeScript, and the 12 releases suggest active maintenance. But it’s not battle-tested at scale in the way that established projects are. Evaluate it accordingly: good fit for internal tools and cost-reduction on non-critical infrastructure, less appropriate as the sole map dependency of a high-traffic production product without a fallback plan.

If deploying the container is the friction point, that’s exactly the kind of one-time infrastructure setup that upready.dev handles for clients.

---

Sources

1. Ethan Sholly, selfh.st — “This Week in Self-Hosted (3 January 2025)”. https://selfh.st/weekly/2025-01-03/

Primary sources:

• GitHub repository and README: https://github.com/dietrichmax/docker-staticmaps (122 stars, AGPL-3.0, single maintainer)
• Project documentation: https://dietrichmax.github.io/docker-staticmaps/
• Docker Hub: https://hub.docker.com/r/mxdcodes/docker-staticmaps