Added guides to environment management by sparafina-earthscope · Pull Request #8 · EarthScope/GeoLab-docs

sparafina-earthscope · 2026-07-08T21:56:44Z

added binder_for_images.md, building_custom_images.md, and managing_environments.md

netlify · 2026-07-08T21:56:48Z

✅ Deploy Preview for earthscope-geolab-docs ready!

Name	Link
🔨 Latest commit	`3b7afb6`
🔍 Latest deploy log	https://app.netlify.com/projects/earthscope-geolab-docs/deploys/6a91d8e54344450008c62faa
😎 Deploy Preview	https://deploy-preview-8--earthscope-geolab-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

sarahw-earthscope

The content of the new pages is fantastic!

The organization of the whole section now feels chaotic, however. What started as a single page of bullet-summary followed by expanded details for each option, now just feels super redundant with those more detailed options linking out to more pages. I'd love to see one overhead page with a brief summary of the different installation options (this should help users differentiate their use case), and then link to the sub-page for the guide on each one.

sarahw-earthscope · 2026-07-15T00:10:36Z

@@ -0,0 +1,159 @@
+# Creating Your Own Python Environment in GeoLab
+
+Python projects rely on add-on packages, which are collections of code that do useful things like process data, make maps, or analyze signals. Different projects often need different packages, or even different versions of the same package. An **environment** is a way to keep all of that organized in one tidy, self-contained workspace.


Add a clarification that they are already inside a conda environment when they launch GeoLab.

sarahw-earthscope · 2026-07-15T00:13:23Z

+conda env create -f environment.yml
+```
+
+Conda will figure out which versions of everything are compatible and download them. This can take a few minutes, which is normal.


We need to add clarification here that these things are getting installed in a NEW environment that doesn't include everything in the geolab-base. Their environment.yml needs to include all the packages they want to install, not just the ones that were missing from base.

sarahw-earthscope · 2026-07-15T00:17:14Z

+
+1. Open a notebook and go to **Kernel > Change Kernel…**
+
+   ![Kernel menu showing the Change Kernel option](./images/select_kernel.png)


images aren't rendering in the build preview, make sure they are included in the MR

sarahw-earthscope · 2026-07-15T00:20:09Z

@@ -7,6 +7,8 @@ When you open GeoLab and select an environment when starting your server, you la
 * [Bring Your Own Image:](#bring-your-own-image) Many other organizations (e.g, NASA, NOAA) maintain their own JupyterHub compute environment images. Many of these will run in GeoLab. 


Add a list item for binder

sarahw-earthscope · 2026-07-15T00:23:43Z

 ## Create a Custom Image
-:::{attention} Section Under Development!
-:::
+You can build a custom own image using our existing image as a template. This strategy is an advanced approach for software with complex installations, and only recommended for users with some prior knowledge of building containers.


These summaries now feel redundant with the summary bullets above and the details on a separate page.

sarahw-earthscope · 2026-07-15T00:30:41Z

+[2i2c guide to binderhub](https://docs.2i2c.org/user/environment/dynamic-imagebuilding/#user-environment-building) - This strategy is an option if you want to use an environment file that extends the base GeoLab image with additional python packages, but don't want to build and host an image. You can specify your environment file once to generate a stable container, and load that at launch time. Note, there's a 15-20 minute overhead to build the image in GeoLab the first time and any time you change the environment file, you will need to consider whether this will save you time in the long run.

- If you need to make extensive software changes, you can build your own image using our existing image as a template. Instructions are located in the `README.md` file in the [GeoLab GitHub repository.]({{ geolab_github }}) You will need to clone the repository, modify the build files to suit your needs, build your container and upload it to a public container registry like DockerHub or AWS ECR, and then select it as 'Other' from the dropdown when you [launch your GeoLab server](../getting_started/server_launch.md). This strategy is an advanced approach for software with complex installations, and only recommended for users with some prior knowledge of building docker containers.
+Follow the instructions to deploy a custom image from a GitHub repository using binder in this [guide](./environments/binder_for_images.md).


It's confusing to have two links here (one to 2i2c, one to our guide), users won't know which one to follow. I'd suggest linking to our guide, and then at the end of that, add "see the 2i2c guide for additional details"

sarahw-earthscope · 2026-07-30T21:54:44Z

Please see notes linked in the jira ticket for suggested improvements to make this easier for first-time image builders to follow.

sarahw-earthscope

See notes linked in the jira ticket for suggested improvements to make this easier for first-time image builders to follow.

sarahw-earthscope

Content looks really good, just a few suggestions on reorganizing some pieces to make the forks more apparent to new users.

sarahw-earthscope · 2026-08-19T15:07:51Z

+%pip install pkgname
+```
+
+For more information about managing environments, go to [`Managing Environments`](./managing_environments.md) for detailed instructions.


The link text should match the title of the target page. It's very confusing that the page titled 'Managing Environments' (this one) is not the one named managing_environments.md , and that page is named something else.

sarahw-earthscope · 2026-08-19T15:08:26Z

+
+While this is the simplest method for building and running a custom image, GeoLab builds the image every time. The build process can take some time and is not ideal for multiple users. By contrast, an image in a repository is pulled directly into JupyterHub and started without waiting for it to be built.
+
+For more information about using Binder, go to [`Binder for Images`](./binder_for_images.md) for detailed instructions on building a repository that works with Binder.


Same here, please make sure the link text matches the page title

sarahw-earthscope · 2026-08-19T15:12:50Z

+
+---
+
+## Installing a Package Without Rebuilding


'build' has another meaning in this section re: images, can we re-title this something like "Installing a package in the current environment" ?

sarahw-earthscope · 2026-08-19T15:20:57Z

+
+Think of an **image** as a recipe and a **container** as a meal made from that recipe. The recipe doesn't change; you can make the same meal over and over. GeoLab does the same thing: it takes your image and launches a fresh session from it every time.
+
+Install Python packages in an image by editing plaintext files that list the required software. A tool called `Docker` reads those files and builds the image. The image must be published in an image repository so GeoLab can access it. Here is the process:


Add a sentence or two about non-python packages.

sarahw-earthscope · 2026-08-19T15:22:05Z

+Install Python packages in an image by editing plaintext files that list the required software. A tool called `Docker` reads those files and builds the image. The image must be published in an image repository so GeoLab can access it. Here is the process:
+
+```text
+Edit config files  →  Docker builds  →  Image  →  Push image to repository  →  GeoLab runs it


This shows up as a line of code with a scroll bar depending on window width. An ordered list or a table might be a better display option.

sarahw-earthscope · 2026-08-19T16:08:25Z

+
+---
+
+## Amazon Web Services Public Elastic Container Registry (ECR)


This should either be a separate page, OR needs a section link from the top of the page to jump straight to here without scrolling through all the GHCR instructions

sarahw-earthscope · 2026-08-19T16:10:37Z

+
+### Getting Public ECR Credentials
+
+Authenticate Docker to a public ECR registry. Use the `ecr-public` command, and note that the region **must** be `us-east-1`:


Suggested change

Authenticate Docker to a public ECR registry. Use the `ecr-public` command, and note that the region **must** be `us-east-1`:

Authenticate Docker to a public ECR registry. Use the `ecr-public` command, and note that the region **must** be `us-east-1` for authentication, regardless of the region you regularly work in.

sarahw-earthscope · 2026-08-19T16:13:07Z

@@ -0,0 +1,182 @@
+# GeoLab Binder
+
+There are two ways to launch a custom environment in GeoLab. The first is to build a Docker image, push it to a registry, and paste the image URL. The second, called **GeoLab Binder**, is to point GeoLab at a GitHub repository and let it build the environment for you. This guide covers how the second approach works and when to use it.


Suggested change

There are two ways to launch a custom environment in GeoLab. The first is to build a Docker image, push it to a registry, and paste the image URL. The second, called **GeoLab Binder**, is to point GeoLab at a GitHub repository and let it build the environment for you. This guide covers how the second approach works and when to use it.

There are two ways to launch a custom environment in GeoLab. The first is to [Build a custom image](custom_image_page.md) and push it to a registry, and specify the image URL when launching GeoLab. The second, called **GeoLab Binder**, is to point GeoLab at a GitHub repository and let it build the environment for you. This guide covers how the second approach works and when to use it.

sarahw-earthscope · 2026-08-19T16:14:17Z

+Both approaches run inside GeoLab, so you have the same access to EarthScope data services either way.
+
+```text
+GitHub repo with config files  →  GeoLab builds image  →  Session launches in GeoLab


Consider reformatting this to a numbered list or table or flow-charty-graphic, instead of single-line text scroll

sarahw-earthscope · 2026-08-19T16:15:38Z

+
+---
+
+## GeoLab Binder vs. Custom Image


I think this context and table might belong on the environment management index page to help someone choose the right fork before diving into the build instructions. It doesn't hurt to reiterate here to help someone confirm they're in the right place... but they need this information before diving into a custome image build, too.

…to guides

added guides

6568ee8

sarahw-earthscope requested changes Jul 15, 2026

View reviewed changes

sarahw-earthscope reviewed Jul 30, 2026

View reviewed changes

sparafina-earthscope added 5 commits August 6, 2026 22:27

update: reworked environments docs

7a7b747

corrections to text and myst.yml

da4a61e

fix: myst.yml, added images, corrections to content

4a9598a

grammatical and typographic fixes

a95b9c3

fixed header references in index.ms

26fb995

sarahw-earthscope requested changes Aug 19, 2026

View reviewed changes

sparafina-earthscope added 2 commits August 28, 2026 12:48

add guide to connect VSCode to GeoLab

6351bed

Merge branch 'guides' of https://github.com/EarthScope/GeoLab-docs in…

3b7afb6

…to guides

		@@ -0,0 +1,159 @@
		# Creating Your Own Python Environment in GeoLab

		Python projects rely on add-on packages, which are collections of code that do useful things like process data, make maps, or analyze signals. Different projects often need different packages, or even different versions of the same package. An environment is a way to keep all of that organized in one tidy, self-contained workspace.


		1. Open a notebook and go to Kernel > Change Kernel…

		![Kernel menu showing the Change Kernel option](./images/select_kernel.png)

		@@ -7,6 +7,8 @@ When you open GeoLab and select an environment when starting your server, you la
		* [Bring Your Own Image:](#bring-your-own-image) Many other organizations (e.g, NASA, NOAA) maintain their own JupyterHub compute environment images. Many of these will run in GeoLab.


		While this is the simplest method for building and running a custom image, GeoLab builds the image every time. The build process can take some time and is not ideal for multiple users. By contrast, an image in a repository is pulled directly into JupyterHub and started without waiting for it to be built.

		For more information about using Binder, go to [`Binder for Images`](./binder_for_images.md) for detailed instructions on building a repository that works with Binder.


		Think of an image as a recipe and a container as a meal made from that recipe. The recipe doesn't change; you can make the same meal over and over. GeoLab does the same thing: it takes your image and launches a fresh session from it every time.

		Install Python packages in an image by editing plaintext files that list the required software. A tool called `Docker` reads those files and builds the image. The image must be published in an image repository so GeoLab can access it. Here is the process:


		---

		## Amazon Web Services Public Elastic Container Registry (ECR)


		### Getting Public ECR Credentials

		Authenticate Docker to a public ECR registry. Use the `ecr-public` command, and note that the region must be `us-east-1`:

		@@ -0,0 +1,182 @@
		# GeoLab Binder

		There are two ways to launch a custom environment in GeoLab. The first is to build a Docker image, push it to a registry, and paste the image URL. The second, called GeoLab Binder, is to point GeoLab at a GitHub repository and let it build the environment for you. This guide covers how the second approach works and when to use it.

Uh oh!

Conversation

sparafina-earthscope commented Jul 8, 2026

Uh oh!

netlify Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for earthscope-geolab-docs ready!

Uh oh!

sarahw-earthscope left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sarahw-earthscope left a comment

Choose a reason for hiding this comment

Uh oh!

sarahw-earthscope left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

netlify Bot commented Jul 8, 2026 •

edited

Loading