Skip to content

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

feat(docker): manual GHCR publish for the demo-app image (#3737)

Igor Dykhta2ecf2cd768ff
diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml
new file mode 100644
index 000000000..245810e2b
--- /dev/null
+++ b/.github/workflows/docker-publish.yml
@@ -0,0 +1,90 @@
+# Manual GHCR publish. Actions → Docker publish → Run workflow → pick branch or tag.
+# The image is built from this repo (not from npm). Smoke-test before push so a
+# failing image never becomes :latest.
+name: Docker publish
+
+on:
+ workflow_dispatch:
+ inputs:
+ update_latest:
+ description: 'Also push the latest tag'
+ type: boolean
+ default: false
+
+concurrency:
+ group: docker-publish
+ cancel-in-progress: false
+
+jobs:
+ publish:
+ runs-on: ubuntu-latest
+ timeout-minutes: 60
+ permissions:
+ contents: read
+ packages: write
+ actions: write
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Set up Docker Buildx
+ uses: docker/setup-buildx-action@v3
+
+ - name: Docker metadata
+ id: meta
+ uses: docker/metadata-action@v5
+ with:
+ images: ghcr.io/${{ github.repository }}
+ tags: |
+ type=raw,value=latest,enable=${{ inputs.update_latest }}
+ type=sha,prefix=sha-
+ type=ref,event=tag
+
+ - name: Build production image
+ uses: docker/build-push-action@v6
+ with:
+ context: .
+ file: docker/Dockerfile
+ load: true
+ provenance: false
+ sbom: false
+ tags: kepler-prod:ci
+ labels: ${{ steps.meta.outputs.labels }}
+ cache-from: type=gha
+ cache-to: type=gha,mode=max
+
+ - name: Smoke-test runtime config
+ run: |
+ docker run -d --name kepler-prod -p 8080:8080 \
+ -e KEPLER_MAPBOX_ACCESS_TOKEN=pk.ci-test \
+ -e KEPLER_PAGE_TITLE=ci-title \
+ kepler-prod:ci
+
+ cleanup() { docker logs kepler-prod || true; docker rm -f kepler-prod || true; }
+ trap cleanup EXIT
+
+ for _ in $(seq 1 30); do
+ if curl -fsS http://127.0.0.1:8080/config.json >/dev/null; then
+ break
+ fi
+ sleep 2
+ done
+
+ curl -fsS http://127.0.0.1:8080/config.json > /tmp/kepler-config.json
+ python3 -c 'import json; c=json.load(open("/tmp/kepler-config.json")); assert c["credentials"]["MapboxAccessToken"]=="pk.ci-test", c; assert c["pageTitle"]=="ci-title", c'
+ curl -fsS http://127.0.0.1:8080/ | grep -q 'id="root"'
+
+ - name: Log in to GHCR
+ uses: docker/login-action@v3
+ with:
+ registry: ghcr.io
+ username: ${{ github.actor }}
+ password: ${{ secrets.GITHUB_TOKEN }}
+
+ - name: Push tags
+ run: |
+ set -euo pipefail
+ echo "${{ steps.meta.outputs.tags }}" | while IFS= read -r tag; do
+ [ -z "$tag" ] && continue
+ docker tag kepler-prod:ci "$tag"
+ docker push "$tag"
+ done
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 015e260d8..e7cdb1aa3 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -1,13 +1,8 @@
-# Prod image smoke test (env-only /config.json). Skipped unless docker packaging changes.
+# Prod image smoke test (env-only /config.json). PRs that touch docker packaging.
+# Master / tags: publish is manual (Actions → Docker publish → Run workflow).
name: Docker CI
on:
- push:
- branches: [master]
- paths:
- - 'docker/**'
- - '.dockerignore'
- - '.github/workflows/docker.yml'
pull_request:
branches: [master]
paths:
@@ -32,10 +27,11 @@ jobs:
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- - name: Validate Compose file
+ - name: Validate Compose files
run: |
printf 'MapboxAccessToken=pk.ci-test\nKEPLER_PAGE_TITLE=ci-title\n' > .env
docker compose -f docker/docker-compose.yml --env-file .env config >/dev/null
+ docker compose -f docker/docker-compose.ghcr.yml --env-file .env config >/dev/null
- name: Build production image
uses: docker/build-push-action@v6
diff --git a/docker/README.md b/docker/README.md
index 584e5485e..eb324ee33 100644
--- a/docker/README.md
+++ b/docker/README.md
@@ -91,7 +91,44 @@ docker compose -f docker/docker-compose.yml --env-file .env up kepler-prod
Then open http://localhost:8080.
-Once the 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`:
+## 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`. 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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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`:
```bash
docker compose -f docker/docker-compose.yml up --no-build kepler-prod
@@ -146,14 +183,6 @@ docker run -p 8080:8080 --env-file .env.kepler \
# KEPLER_PAGE_TITLE=kepler.gl demo
```
-No-build deploy once a registry image exists (future) — env-only example:
-
-```bash
-docker run -p 8080:8080 \
- -e KEPLER_MAPBOX_ACCESS_TOKEN='pk.your-token' \
- ghcr.io/keplergl/kepler.gl:<tag>
-```
-
## Notes
- The build context must be the repository root (both Dockerfiles reference `src/`, `scripts/`, etc.).
diff --git a/docker/docker-compose.ghcr.yml b/docker/docker-compose.ghcr.yml
new file mode 100644
index 000000000..be1feba35
--- /dev/null
+++ b/docker/docker-compose.ghcr.yml
@@ -0,0 +1,32 @@
+# No-build demo-app. Pulls the published image; does not clone or compile kepler.gl.
+#
+# curl -fsSO https://raw.githubusercontent.com/keplergl/kepler.gl/master/docker/docker-compose.ghcr.yml
+# docker compose -f docker-compose.ghcr.yml up
+#
+# Optional config.json (same schema as docker/config.example.json).
+# :ro is fine with no KEPLER_* overrides. If you also set env overrides, use a
+# writable mount — the entrypoint must write the merged file.
+# volumes:
+# - ./config.json:/app/dist/config.json:ro
+#
+# Pin a digest or sha tag in production instead of :latest.
+
+services:
+ kepler:
+ image: ghcr.io/keplergl/kepler.gl:latest
+ ports:
+ - "8080:8080"
+ environment:
+ KEPLER_MAPBOX_ACCESS_TOKEN: ${MapboxAccessToken:-}
+ KEPLER_MAPBOX_EXPORT_TOKEN: ${MapboxExportToken:-}
+ KEPLER_DROPBOX_CLIENT_ID: ${DropboxClientId:-}
+ KEPLER_CARTO_CLIENT_ID: ${CartoClientId:-}
+ KEPLER_FOURSQUARE_CLIENT_ID: ${FoursquareClientId:-}
+ KEPLER_FOURSQUARE_DOMAIN: ${FoursquareDomain:-}
+ KEPLER_FOURSQUARE_API_URL: ${FoursquareAPIURL:-}
+ KEPLER_FOURSQUARE_USER_MAPS_URL: ${FoursquareUserMapsURL:-}
+ KEPLER_GOOGLE_DRIVE_CLIENT_ID: ${GoogleDriveClientId:-}
+ KEPLER_MAP_CONFIG_URL: ${KEPLER_MAP_CONFIG_URL:-}
+ KEPLER_MAP_URL: ${KEPLER_MAP_URL:-}
+ KEPLER_PAGE_TITLE: ${KEPLER_PAGE_TITLE:-}
+ KEPLER_CONFIG_HREF: ${KEPLER_CONFIG_HREF:-}