Docker

• Create a custom image
• Use an existing image
• How it works
• Essential parts
• FAQ

Create a custom image

Building the Dockerfile without changing any build options:

docker build -t stac-browser:v1 .

Run the container for a specific URL:

docker run -p 8080:8080 -e SB_catalogUrl="https://earth-search.aws.element84.com/v1/" stac-browser:v1

STAC Browser is now available at http://localhost:8080

---

You can pass further options to STAC Browser to customize it to your needs.

The build-only options historyMode and SB_CONFIG (for loading an external config file) can be provided as a build argument when building the Dockerfile.

For example:

docker build -t stac-browser:v1 --build-arg historyMode=hash .

SB_CONFIG lets you overlay a custom config module (e.g. for options like preprocessSTAC that can only be set in a config file) without modifying the Dockerfile:

docker build -t stac-browser:v1 --build-arg SB_CONFIG=./config.custom.mjs .

All other options, except the ones that are explicitly excluded from CLI/ENV usage, can be passed as environment variables when running the container. For example, to run the container with a pre-defined catalogUrl and catalogTitle:

docker run -p 8080:8080 -e SB_catalogUrl="https://earth-search.aws.element84.com/v1/" -e SB_catalogTitle="Earth Search" stac-browser:v1

pathPrefix can also be set at container startup via SB_pathPrefix (when DYNAMIC_CONFIG is enabled, the default):

docker run -p 8080:8080 -e SB_pathPrefix="/browser/" -e SB_catalogUrl="https://earth-search.aws.element84.com/v1/" stac-browser:v1

If you want to pass all the other arguments to npm run build directly, you can modify to the Dockerfile as needed.

STAC Browser is now available at http://localhost:8080/browser/. Requests to http://localhost:8080/browser (no trailing slash) are redirected there.

Use an existing image

Since version 3.1.1, you can add an existing image from Packages to your docker-compose.yml:

services:
  stac-browser:
    image: ghcr.io/radiantearth/stac-browser:latest
    ports:
      - 8080:8080
    environment:
      SB_catalogUrl: "https://localhost:7188"

How it works

The docker image uses a multi stage build. The first stage is based on a node image and runs npm run build to produce a /dist folder with static files (HTML, CSS, and JavaScript). The second stage is based on an nginx image that serves the folder with static files. At startup, the entrypoint applies SB_pathPrefix to nginx and generates runtime-config.js. So, essentially, in the end you get an nginx instance that serves static files.

Essential parts

1. Dockerfile - contains information on how to build the image.
2. docker/default.conf - nginx configuration template; ${STAC_PATH_PREFIX} is substituted at startup.
3. docker/docker-entrypoint.sh - a start script to read the passed variables, render the nginx config, and produce the runtime-config.js file.

FAQ

Can I use ghcr.io/radiantearth/stac-browser image with the pathPrefix?

Yes — pass -e SB_pathPrefix="/browser/" at container startup. See pathPrefix.

How do I specify buildTileUrlTemplate via docker env?

You can not. Consider modifying the dockerfile and using a custom config.js file (or runtime-config.js for runtime configuration)