Improve docker documentation (#512)

* docs: Add more description on how the docker image works * docs: mention docker docs in readme * docs: fix the link from README * docs: move out docker section from README to a separate file * docs: couple of editorial changes * Update README.md * Apply suggestions from code review --------- Co-authored-by: Matthias Mohr <[email protected]>
radiantearth · Dec 10, 2024 · c456743 · c456743
1 parent 37064de
commit c456743
Show file tree

Hide file tree

Showing 2 changed files with 86 additions and 58 deletions.
diff --git a/README.md b/README.md
@@ -252,64 +252,7 @@ STAC Browser supports some non-standardized extensions to the STAC specification
 
 ## Docker
 
-### Create a custom image
-
-Building the Dockerfile without changing any build options:
-
-```bash
-docker build -t stac-browser:v1 .
-```
-
-Run the container for a specific URL:
-
-```bash
-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
-[`pathPrefix`](docs/options.md#pathprefix) and [`historyMode`](docs/options.md#historymode)
-can be provided as a
-[build argument](https://docs.docker.com/engine/reference/commandline/build#set-build-time-variables---build-arg)
-when building the Dockerfile.
-
-For example:
-
-```bash
-docker build -t stac-browser:v1 --build-arg pathPrefix="/browser/" --build-arg historyMode=hash .
-```
-
-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`](docs/options.md#catalogurl) and [`catalogTitle`](docs/options.md#catalogtitle):
-
-```bash
-docker run -p 8080:8080 -e SB_catalogUrl="https://earth-search.aws.element84.com/v1/" -e SB_catalogTitle="Earth Search" 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`
-
-### Use an existing image
-
-Since version 3.1.1, you can add an existing image from [Packages](https://github.com/radiantearth/stac-browser/pkgs/container/stac-browser) to your docker-compose.yml:
-
-```
-services:
-  stac-browser:
-    image: ghcr.io/radiantearth/stac-browser:latest
-    ports:
-      - 8080:8080
-    environment:
-      SB_catalogUrl: "https://localhost:7188"
-```
+You can use the Docker to work with STAC Browser. Please read [Docker documentation](docs/docker.md) for more details.
 
 ## Contributing
 

diff --git a/docs/docker.md b/docs/docker.md
@@ -0,0 +1,85 @@
+# Docker
+
+Note: Docker might not be an ideal way to deploy STAC Browser in production. Consider using a web host, cloud storage, or a CDN. 
+
+## Create a custom image
+
+Building the Dockerfile without changing any build options:
+
+```bash
+docker build -t stac-browser:v1 .
+```
+
+Run the container for a specific URL:
+
+```bash
+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
+[`pathPrefix`](docs/options.md#pathprefix) and [`historyMode`](docs/options.md#historymode)
+can be provided as a
+[build argument](https://docs.docker.com/engine/reference/commandline/build#set-build-time-variables---build-arg)
+when building the Dockerfile.
+
+For example:
+
+```bash
+docker build -t stac-browser:v1 --build-arg pathPrefix="/browser/" --build-arg historyMode=hash .
+```
+
+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`](docs/options.md#catalogurl) and [`catalogTitle`](docs/options.md#catalogtitle):
+
+```bash
+docker run -p 8080:8080 -e SB_catalogUrl="https://earth-search.aws.element84.com/v1/" -e SB_catalogTitle="Earth Search" 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`
+
+## Use an existing image
+
+Since version 3.1.1, you can add an existing image from [Packages](https://github.com/radiantearth/stac-browser/pkgs/container/stac-browser) 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 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 and deals with the build-only options such as  `pathPrefix`.
+So, essentialy, in the end you get an nginx instance that serves static files.
+
+## Essential parts
+
+1. [Dockerfile](../Dockerfile) - contains information on how to build the image.
+2. [docker/default.conf](../docker/default.conf) - nginx configuration template, where `<pathPrefix>` is replaced during build.
+3. [docker/docker-entrypoint.sh](../docker/docker-entrypoint.sh) - a start script to read the passed variables and produce the `config.js` file.
+
+## FAQ
+
+> Can I use `ghcr.io/radiantearth/stac-browser` image with the `pathPrefix`?
+
+You can not. You need to build your own image because `pathPrefix` is a build-only option.
+
+> How do I specify `buildTileUrlTemplate` via docker env?
+
+You can not. Consider modifying the dockerfile and using a custom `config.js` file