Skip to content

Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.

feat: Add Docker setup for running kepler.gl demo app locally (#3458)

Igor Dykhtaf7cc780d14c3
diff --git a/.dockerignore b/.dockerignore
index c06689d14..c2c7d8932 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -4,3 +4,9 @@ dist/
node_modules/
__pycache__/
build/
+.git/
+website/
+bindings/
+test/
+docs/
+*.log
diff --git a/docker/Dockerfile b/docker/Dockerfile
new file mode 100644
index 000000000..1d2628d92
--- /dev/null
+++ b/docker/Dockerfile
@@ -0,0 +1,43 @@
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+RUN apk add --no-cache git python3 make g++ bash sed
+
+RUN corepack enable && corepack prepare [email protected] --activate
+
+# Copy dependency manifests first for better layer caching
+COPY package.json yarn.lock .yarnrc.yml ./
+COPY --parents src/*/package.json ./
+COPY --parents examples/demo-app/package.json examples/demo-app/yarn.lock examples/demo-app/.yarnrc.yml ./
+
+# Skip all postinstall scripts to avoid building the gl native package (GPU headers not available)
+RUN yarn config set enableScripts false && \
+ yarn install && \
+ yarn config set enableScripts true
+
+# Selectively run esbuild postinstall (needed for the correct platform binary)
+RUN cd node_modules/esbuild && node install.js
+
+# Now copy the full source
+COPY . .
+
+RUN yarn fix-dependencies
+RUN yarn workspaces foreach -At run stab
+
+WORKDIR /app/examples/demo-app
+
+RUN yarn install
+RUN yarn build
+
+FROM node:20-alpine AS runtime
+
+WORKDIR /app
+
+RUN npm install -g serve@14
+
+COPY --from=builder /app/examples/demo-app/dist ./dist
+
+EXPOSE 8080
+
+CMD ["serve", "-s", "dist", "-l", "8080"]
diff --git a/docker/Dockerfile.dev b/docker/Dockerfile.dev
new file mode 100644
index 000000000..473e47c66
--- /dev/null
+++ b/docker/Dockerfile.dev
@@ -0,0 +1,37 @@
+FROM node:20-alpine
+
+WORKDIR /app
+
+RUN apk add --no-cache git python3 make g++ bash sed
+
+# Provide a no-op xdg-open so the dev server doesn't crash trying to open a browser
+RUN printf '#!/bin/sh\nexit 0\n' > /usr/local/bin/xdg-open && chmod +x /usr/local/bin/xdg-open
+
+RUN corepack enable && corepack prepare [email protected] --activate
+
+# Copy dependency manifests first for better layer caching
+COPY package.json yarn.lock .yarnrc.yml ./
+COPY --parents src/*/package.json ./
+COPY --parents examples/demo-app/package.json examples/demo-app/yarn.lock examples/demo-app/.yarnrc.yml ./
+
+# Skip all postinstall scripts to avoid building the gl native package (GPU headers not available)
+RUN yarn config set enableScripts false && \
+ yarn install && \
+ yarn config set enableScripts true
+
+# Selectively run esbuild postinstall (needed for the correct platform binary)
+RUN cd node_modules/esbuild && node install.js
+
+# Now copy the full source
+COPY . .
+
+RUN yarn fix-dependencies
+RUN yarn workspaces foreach -At run stab
+
+WORKDIR /app/examples/demo-app
+
+RUN yarn install
+
+EXPOSE 8080
+
+CMD ["yarn", "start:local"]
diff --git a/docker/README.md b/docker/README.md
new file mode 100644
index 000000000..494e64d53
--- /dev/null
+++ b/docker/README.md
@@ -0,0 +1,65 @@
+# 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`.
+- **Dockerfile.dev** — development build with esbuild watch mode inside the container.
+
+## Prerequisites
+
+1. [Docker](https://docs.docker.com/get-docker/) installed and running
+2. Create a `.env` file at the repository root (copy from `.env.template`):
+
+```bash
+cp .env.template .env
+```
+
+Fill in at least `MapboxAccessToken` for the map to render.
+
+## Running with Docker Compose
+
+From the repository root:
+
+```bash
+# Development mode (esbuild watch inside the container)
+docker compose -f docker/docker-compose.yml up kepler-dev
+
+# Production mode (static build served by serve)
+docker compose -f docker/docker-compose.yml up kepler-prod
+```
+
+Then open http://localhost:8080.
+
+To rebuild after code changes on the host:
+
+```bash
+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. via `docker exec`).
+
+## Running with Docker directly
+
+### Development
+
+```bash
+docker build -f docker/Dockerfile.dev -t kepler-dev .
+docker run -p 8080:8080 --env-file .env -e NODE_ENV=local kepler-dev
+```
+
+### Production
+
+Make sure `.env` exists at the root — env vars are baked in at build time:
+
+```bash
+docker build -f docker/Dockerfile -t kepler-prod .
+docker run -p 8080:8080 kepler-prod
+```
+
+## Notes
+
+- The build context must be the repository root (both Dockerfiles reference `src/`, `scripts/`, etc.).
+- The `.dockerignore` at the root excludes `node_modules/`, `.git/`, `website/`, `bindings/`, `test/`, and `docs/` to keep the build context small.
+- All postinstall scripts are disabled during `yarn install` to avoid building the `gl` native package (requires GPU headers, only used for tests). The `esbuild` platform binary is then installed selectively since it's required for bundling.
+- Environment variables like `MapboxAccessToken` are read from the `.env` file copied into the build context. Rebuild the image to change them.
+- The dev image provides a no-op `xdg-open` to prevent the server from crashing when it tries to open a browser.
diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml
new file mode 100644
index 000000000..02b60cc85
--- /dev/null
+++ b/docker/docker-compose.yml
@@ -0,0 +1,18 @@
+services:
+ kepler-dev:
+ build:
+ context: ..
+ dockerfile: docker/Dockerfile.dev
+ ports:
+ - "8080:8080"
+ env_file:
+ - ../.env
+ environment:
+ - NODE_ENV=local
+
+ kepler-prod:
+ build:
+ context: ..
+ dockerfile: docker/Dockerfile
+ ports:
+ - "8080:8080"