Added guides to environment management

advanced_topics/environments/binder_for_images.md

@@ -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.
+
+---
+
+## What Is GeoLab Binder?
+
+GeoLab Binder lets you launch a session from a GitHub repository instead of a prebuilt image. You put configuration files in your repo that describe what packages you need, and GeoLab builds the environment automatically when you start a session.
+
+Behind the scenes, GeoLab reads the Dockerfile and configuration files in your repository and builds the container image for you. You write the Dockerfile (using the same template as a custom image), but you never run Docker locally or push to a registry, as GeoLab handles the build.
+
+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
+```
+
+---
+
+## GeoLab Binder vs. Custom Image
+
+Both approaches use GeoLab's environment selector, but they use different options. The difference is what you select and what you paste.
+
+| | **GeoLab Binder** | **Custom Image** |
+| --- | --- | --- |
+| Menu option | **Build your own image** | **Other** |
+| What you paste | A GitHub repo URL | A container registry URL (`ghcr.io/...`) |
+| Who builds the image | GeoLab, automatically from your repo | You, locally with Docker |
+| What you need | Dockerfile + config files in a GitHub repo | Docker Desktop, local build, registry push |
+| EarthScope data access | Yes | Yes |
+| How updates work | Push a commit, and the next launch picks up the changes | Rebuild and push a new image tag |
+| Best for | Getting started quickly, iterating, sharing a repo | Stable, versioned environments; full Docker control |
+
+**Use GeoLab Binder when** you want to share a GitHub repository as a runnable environment without running Docker locally or managing a container registry.
+
+**Use a custom image when** you need a fixed, versioned environment that won't change between sessions, or when you need more control than config files allow. See [Building a Custom GeoLab Image](./building-custom-images.md).
+
+---
+
+## Before You Start
+
+You need:
+
+- A **GitHub account** and a **GitHub repository** for your project.
+- A GeoLab account at [GeoLab](https://geolab.earthscope.cloud).
+
+No local Docker builds or container registry required.
+
+---
+
+## Step 1: Set Up Your GitHub Repository
+
+Create a new repository on GitHub (or use an existing one). Add your notebooks and at least one configuration file:
+
+```text
+my-project/
+├── Dockerfile            ← required (copy from the geolab-base template)
+├── environment.yml       ← your packages (conda)
+├── requirements.txt      ← PyPI-only packages (optional)
+├── apt.txt               ← system software (optional, rarely needed)
+├── postBuild             ← setup commands to run after install (optional)
+└── my_notebook.ipynb     ← your notebooks
+```
+
+Copy the `Dockerfile` from the `geolab-base` template at [EarthScope/GeoLab](https://github.com/EarthScope/GeoLab/tree/main/geolab-base) and leave it unchanged. All your customization goes in the other files. GeoLab Binder reads everything in the repo and builds the image when you launch.
+
+---
+
+## Step 2: Write Your Configuration Files
+
+### `environment.yml`: Your Main Package List
+
+```yaml
+name: my-binder-env
+channels:
+  - conda-forge
+dependencies:
+  - python=3.11
+  - numpy
+  - matplotlib
+  - obspy
+```
+
+### `requirements.txt`: PyPI-only Packages (If Needed)
+
+```text
+some-pypi-package==1.2.3
+```
+
+### `apt.txt`: System Software (If Needed)
+
+```text
+build-essential
+```
+
+### `postBuild`: One-time Setup Commands (Optional)
+
+If you need to run something after packages install, such as downloading a data file or enabling a Jupyter extension, create a `postBuild` file:
+
+```bash
+#!/bin/bash
+set -e
+jupyter labextension install my-extension
+```
+
+Before committing, mark it executable:
+
+```bash
+chmod +x postBuild
+git add postBuild
+git commit -m "add postBuild script"
+```
+
+These files use the exact same format as the custom image template. If you've worked through [Building a Custom GeoLab Image](./building-custom-images.md), you can reuse them directly.
+
+Once your files are ready, commit, and push them to GitHub:
+
+```bash
+git add environment.yml requirements.txt apt.txt
+git commit -m "add environment configuration"
+git push
+```
+
+If this is a new repository, you may need to set the upstream branch on your first push:
+
+```bash
+git push -u origin main
+```
+
+---
+
+## Step 3: Launch from Your Repo in GeoLab
+
+1. Go to [earthscope.org/data/geolab](https://www.earthscope.org/data/geolab/) and click **Launch GeoLab**.
+2. Enter your username and password, then click **Continue**.
+3. In the environment selector, choose **Build your own image**.
+4. In the **Repository** field, paste the git clone URL for your repository:
+
+   ```text
+   https://github.com/your-github-username/my-project.git
+   ```
+
+5. Click **Build Image**. GeoLab will build the environment from your repository. This can take several minutes the first time.
+6. When you receive a notification that the build is complete, click **Start**.
+
+> **If the build fails:** Check the build log for error messages. Common causes are a misspelled package name, an unavailable package version, or a syntax error in `environment.yml`. Fix the file, push the commit, and try again.
+
+---
+
+## Step 4: Share Your Environment
+
+To share your environment with someone else, give them the git clone URL for your repository. They follow the same steps: go to GeoLab, choose **Build your own image**, paste the URL, and launch.
+
+Because the environment is defined by files in the repo, anyone who uses the same URL gets the same packages. If you update `environment.yml` and push, the next person to launch picks up the new version automatically.
+
+---
+
+## Updating Your Environment
+
+Edit your configuration files, commit, and push. The next GeoLab launch from that repo URL will rebuild with the updated packages.
+
+```bash
+# edit environment.yml, then:
+git add environment.yml
+git commit -m "add pandas to environment"
+git push
+```
+
+> **Note:** A new commit triggers a fresh build on the next launch. If you're changing packages frequently, expect slower first launches while GeoLab rebuilds the image.
+
+---
+
+## Quick Reference
+
+| What you want to do | How |
+| --- | --- |
+| Define your packages | `environment.yml` (conda), `requirements.txt` (PyPI) |
+| Launch from a repo | GeoLab → Start Server → Build your own image → paste git clone URL |
+| Share your environment | Share the git clone URL (`https://github.com/username/repo.git`) |
+| Update your environment | Edit config files, commit, and push |
+| Use a fixed versioned environment instead | See [Building a Custom GeoLab Image](./building-custom-images.md) |