Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.
Docker Setup for kepler.gl Demo App
Two Dockerfiles are provided:
- Dockerfile — production multi-stage build. Compiles the demo-app to static files and serves with
serve. Tokens and other deploy-specific settings are injected at runtime via/config.jsonand/orKEPLER_*env vars (not baked into the image). - Dockerfile.dev — development build with esbuild watch mode inside the container.
Prerequisites
- Docker installed and running
- For local prod Compose with env overrides, create a
.envfile at the repository root (copy from.env.template):
cp .env.template .env
Fill in at least MapboxAccessToken if you want Mapbox basemaps. MapLibre/Carto defaults work without a token.
Runtime configuration
The production image reads /config.json from the static root (/app/dist/config.json). Copy the minimal starter and fill in only what you need (empty credential strings are ignored):
cp docker/config.example.json docker/config.json
docker/config.full-example.json lists every supported key. Use it as a reference — do not mount it as-is (mapUrl boots a sample map, and mapStyle.mapStyles replaces the built-in basemap list).
Mount it when running (uncomment the volumes block in docker-compose.yml after creating the file). Pick one of these patterns — do not combine a read-only mount with KEPLER_* overrides (the entrypoint must write the merged file, and the container exits if that write fails). Without KEPLER_* overrides there is nothing to write, so a read-only root filesystem still starts and serves with build-time defaults:
# A) Config file only (read-only is fine)
volumes:
- ./config.json:/app/dist/config.json:ro
# B) Config file + KEPLER_* env overrides (read-write mount required)
volumes:
- ./config.json:/app/dist/config.json
environment:
KEPLER_MAPBOX_ACCESS_TOKEN: ${MapboxAccessToken}
# C) Env only — no volume; entrypoint writes /app/dist/config.json inside the container
environment:
KEPLER_MAPBOX_ACCESS_TOKEN: ${MapboxAccessToken}
KEPLER_PAGE_TITLE: My Kepler
Supported KEPLER_* env vars (used in patterns B and C):
| Env var | Config path |
|---|---|
KEPLER_MAPBOX_ACCESS_TOKEN |
credentials.MapboxAccessToken |
KEPLER_MAPBOX_EXPORT_TOKEN |
credentials.MapboxExportToken |
KEPLER_DROPBOX_CLIENT_ID |
credentials.DropboxClientId |
KEPLER_CARTO_CLIENT_ID |
credentials.CartoClientId |
KEPLER_FOURSQUARE_CLIENT_ID |
credentials.FoursquareClientId |
KEPLER_FOURSQUARE_DOMAIN |
credentials.FoursquareDomain |
KEPLER_FOURSQUARE_API_URL |
credentials.FoursquareAPIURL |
KEPLER_FOURSQUARE_USER_MAPS_URL |
credentials.FoursquareUserMapsURL |
KEPLER_GOOGLE_DRIVE_CLIENT_ID |
credentials.GoogleDriveClientId |
KEPLER_MAP_CONFIG_URL |
mapConfigUrl |
KEPLER_MAP_URL |
mapUrl |
KEPLER_PAGE_TITLE |
pageTitle |
KEPLER_CONFIG_HREF |
Browser fetch URL for config.json (injected into index.html) |
The browser requests /config.json by default (origin root — same as GHCR, kepler.gl.com, and this image on port 8080). SPA routes like /demo/:id still hit that origin-root file, so the default needs no env. Set KEPLER_CONFIG_HREF only to read the config from somewhere else, for example KEPLER_CONFIG_HREF=/shared/kepler-config.json or an absolute URL on another host (CORS applies).
Serving the app itself at a browser-visible sub-path such as https://host/kepler/ is not supported: index.html loads /bundle.js and /bundle.css from the origin root, the router declares its routes at /, /auth, and /demo… with no basename, and loadSample pushes /demo/<id>. A prefixed pathname therefore matches no route and renders an empty page. KEPLER_CONFIG_HREF relocates the config request only — it does not add sub-path support. Serve the app at the origin root; a reverse proxy in front is fine as long as it maps those root paths.
mapConfigUrl / KEPLER_MAP_CONFIG_URL replaces only the sample-gallery catalogue (samples.json). It does not rewrite compile-time DATA_URL or ASSETS_URL. Each catalogue row must use absolute dataUrl, configUrl, imageUrl (and keplergl / remoteDatasetConfigUrl when present) — the app does not prefix those paths. ASSETS_URL is only the "Try sample data" tab thumbnail CDN. A fully self-hosted gallery works by pointing mapConfigUrl at your own catalogue; see docker/samples.example.json.
See docker/config.full-example.json for every key supported today (credentials, pageTitle, mapConfigUrl, mapUrl, reducer mapStyle, KeplerGl mapStyles / mapStylesReplaceDefault, and serializable applicationConfig fields).
Not JSON-configurable (need a source build): plugins, table, database, baseMapLibraryConfig (functions). Map style layerGroups[].filter callbacks also cannot be expressed in JSON.
Running with Docker Compose
From the repository root:
# Optional runtime config — then uncomment `volumes` in docker-compose.yml
cp docker/config.example.json docker/config.json
# Development mode (esbuild watch inside the container; still uses build-time .env)
docker compose -f docker/docker-compose.yml --env-file .env up kepler-dev
# Production mode (static build + runtime config / KEPLER_* from .env)
# Without a mounted config.json, credential and KEPLER_MAP_* / KEPLER_PAGE_TITLE env still apply.
docker compose -f docker/docker-compose.yml --env-file .env up kepler-prod
Then open http://localhost:8080.
Published image (GHCR)
The production image is built from this repo (local @kepler.gl/* source, not npm) and published to ghcr.io/keplergl/kepler.gl as a multi-arch image (linux/amd64 and linux/arm64). Tokens are still injected at runtime. No npm publish is required. The image is not rebuilt on every master commit.
Publish from GitHub Actions: Actions → Docker publish → Run workflow. Use the branch/tag picker at the top, then launch. Check Also push the latest tag only when this build should become :latest (off by default so a branch test cannot overwrite it).
Tags that get pushed:
sha-<short>— always- the git tag name — when you run the workflow from a tag
latest— when that checkbox is on
No-build (no clone). Env-only:
docker run -p 8080:8080 \
-e KEPLER_MAPBOX_ACCESS_TOKEN='pk.your-token' \
ghcr.io/keplergl/kepler.gl:latest
Or Compose — download docker/docker-compose.ghcr.yml and run:
curl -fsSO https://raw.githubusercontent.com/keplergl/kepler.gl/master/docker/docker-compose.ghcr.yml
docker compose -f docker-compose.ghcr.yml up
From this repo, with the root .env mapped like the build-from-source Compose file:
docker compose -f docker/docker-compose.ghcr.yml --env-file .env up
Pin sha-… (or a release tag) in production instead of latest. After the first publish, set the kepler.gl package visibility to public under the keplergl GitHub Packages settings if pulls are anonymous.
Running with Docker Compose (build from source)
Once a locally built image exists, omit --build so Compose reuses it and starts in seconds, not minutes. Pass --build only after source or Dockerfile changes. If Compose still starts a build, force the existing image with --no-build:
docker compose -f docker/docker-compose.yml up --no-build kepler-prod
To rebuild after code changes on the host:
docker compose -f docker/docker-compose.yml up --build kepler-dev
Note: The dev container does not mount the host source tree, so changes you make on the host require a rebuild (
--build). The esbuild watch mode only picks up changes made inside the container itself (e.g. viadocker exec).
Running with Docker directly
Development
docker build -f docker/Dockerfile.dev -t kepler-dev .
docker run -p 8080:8080 --env-file .env -e NODE_ENV=local kepler-dev
Production
Build once, then choose a single runtime pattern.
Creating a root .env does not export variables into your shell. For docker run, either pass values explicitly, use --env-file with KEPLER_* keys, or load .env into the shell first (set -a && source .env && set +a) so $MapboxAccessToken expands.
docker build -f docker/Dockerfile -t kepler-prod .
# A) Config file only
docker run -p 8080:8080 \
-v "$PWD/docker/config.json:/app/dist/config.json:ro" \
kepler-prod
# B) Config file + KEPLER_* overrides (RW mount)
# Option: explicit value
docker run -p 8080:8080 \
-e KEPLER_MAPBOX_ACCESS_TOKEN='pk.your-token' \
-v "$PWD/docker/config.json:/app/dist/config.json" \
kepler-prod
# Option: load root .env into the shell, then expand MapboxAccessToken
# set -a && source .env && set +a
# docker run ... -e KEPLER_MAPBOX_ACCESS_TOKEN="$MapboxAccessToken" ...
# C) Env only — prefer --env-file with KEPLER_* keys (see table above)
docker run -p 8080:8080 --env-file .env.kepler \
kepler-prod
# Example .env.kepler:
# KEPLER_MAPBOX_ACCESS_TOKEN=pk.your-token
# KEPLER_PAGE_TITLE=kepler.gl demo
Notes
- The build context must be the repository root (both Dockerfiles reference
src/,scripts/, etc.). - The
.dockerignoreat the root excludes nestednode_modules/, other examples,.git,website/,bindings/,test/,docs/, and.env*so secrets are not copied into the build. Yarn installs use a BuildKit cache mount so lockfile rebuilds reuse downloaded packages. Docker Desktop and Compose v2 enable BuildKit by default; ifdocker buildfails on--mount, run it withDOCKER_BUILDKIT=1. - All postinstall scripts are disabled during
yarn installto avoid building theglnative package (requires GPU headers, only used for tests). Theesbuildplatform binary is then installed selectively since it's required for bundling. - Production images are built without baking Mapbox/cloud tokens. Change tokens by remounting
config.jsonor updatingKEPLER_*env and restarting — no rebuild. - The dev image still reads
.envat container start for esbuilddefine(watch/rebuild path). Prefer the prod image for deployable runtime injection. - The dev image provides a no-op
xdg-opento prevent the server from crashing when it tries to open a browser.