Proposal: new `versatiles-server` Docker image

[MichaelKreil]

Proposal: new versatiles-server Docker image

Motivation

Today we offer three images on the "serve a map" axis:

Image	What it bundles	Config at runtime
versatiles	binary only	CLI flags only
versatiles-frontend	binary + one pre-bundled frontend variant (baked at build time)	CLI flags only
versatiles-nginx	binary + nginx + certbot + env-var-driven entrypoint	rich env-var config (FRONTEND, etc.)

There's a gap in the middle. Users who deploy behind an external TLS terminator (Clever Cloud, fly.io, k8s ingress, CloudFront, etc.) want the runtime configurability of versatiles-nginx without nginx/certbot. Right now they have two bad options:

• Use versatiles-frontend and rebuild whenever they want a different frontend variant or data file.
• Use versatiles-nginx and disable nginx, which is wasteful and confusing.

User feedback confirming this gap: Jérémie (Olvid) built a custom image on top of versatiles-frontend precisely to get env-var-driven config in a Clever Cloud deployment.

Design

Add a new image versatiles-server (Alpine + Debian variants) that sits between versatiles-frontend and versatiles-nginx:

• Bundles: versatiles binary + a runtime entrypoint (no nginx, no certbot)
• Config: entirely via environment variables (see below)
• Frontend handling: downloaded on first start based on FRONTEND, cached in a volume — reuses versatiles-nginx/scripts/fetch_frontend.sh
• Data handling: local paths or remote URLs via DATA_FILES; remote files are fetched on first start and optionally refreshed by a background poller

Environment variables

Designed so a developer can scan this once and tell whether the image fits their deployment.

Variable	Required	Default	Description
DATA_FILES	yes	https://download.versatiles.org/osm.versatiles	Space-separated list of .versatiles file paths or URLs to serve. Remote URLs are downloaded on first start.
FRONTEND	no	standard	Frontend variant: standard | dev | min | tiny | blank | none. Same values as versatiles-nginx.
SERVER_PUBLIC_URL	no	—	Public base URL (e.g. https://map.example.org). Passed to versatiles so emitted TileJSON / styles reference this host.
PORT	no	8080	Port the server binds to inside the container.
STATIC_FILES	no	—	Space-separated local paths to additional static tar archives to serve.
AUTO_UPDATE	no	no	If set (e.g. yes), a background poller tries to download new remote DATA_FILES every 14 days and atomically swaps.

Filesystem layout

The working directory is /data, split into three subdirectories with distinct lifecycles:

Path	Contents	Typical mount
/data/maps/	.versatiles data files	persistent volume (large, expensive to re-fetch)
/data/frontend/	Downloaded frontend tarball	regenerable cache; safe to be ephemeral
/data/static/	User-provided static tar archives	bind mount, often read-only

Relative paths in env vars resolve against the matching subdirectory: DATA_FILES="osm.versatiles" → /data/maps/osm.versatiles, STATIC_FILES="custom.tar" → /data/static/custom.tar. URLs in DATA_FILES are downloaded to /data/maps/ using the URL's basename. Mounting a single volume at /data works for casual setups; mounting sub-volumes lets operators size and back up each lifecycle independently.

[jmartel-olvid]

Hi,

Here are a few notes from the comparison with my own "extended" docker image.

• DATA_FILES: in my case remote urls are not supposed to be downloaded locally as they reference an s3 bucket (and my docker container does not own a local storage in clever cloud) . Not sure if the download file locally use case can be useful, if yes, I am not sure what is the best answer. Maybe we can add a different behaviour for any s3:// file, or simply add an REMOTE_DATA_FILES env variable ?

• STATIC_FILES: same use case, in my use case I added a REMOTE_STATIC_FILES env variable to serve static files hosted in s3 (but they are downloaded locally there). I use it to add extra styles packaged in tar ball with json style, fonts and glyphs. It might be possible to add support for remote url to in STATIC_FILES if this feature seems pertinent.

• SERVER_PUBLIC_URL: Is that OK that the variable is optional with no default value ?

[jmartel-olvid]

It's been while since I worked on versatiles, correct me if I am wrong but I cannot see anything to generate styles on the fly to get a real plug and play map server.

To support it it might be necessary to:

• make PUBLIC_SERVER_URL mandatory / with a default value (to set in JSONStyle urls)
• add a way to enable styles ? Or parse passed data files to determine which style can be completed ? In my case I used a STYLES=colorful,satellite variable but it is not really handy.

To achieve this I use a style builder script on start.