View Source

Read time: 6 minutes. Short version: your project can run notebooks on a software image your team built, with the packages you need already installed. You write a short Dockerfile on top of the platform's base image, the platform builds it for you, and your project admin registers it in RPAdmin. It then appears in the Images list on the launch page for your project's members only.

What it is

Every server on the Research Platform starts from a software image: the operating system, Python, JupyterLab, and the packages inside it. The platform ships ready-made images, such as the Earth Science Server. Until now, anything else meant installing packages by hand every session, or asking the platform team.

Bring your own image lets a project add its own image to the launch page. Your team decides what goes in it. The platform builds it, checks it, and offers it to your members next to the standard images.

The rules, up front

Rule	Why
The image must start from the platform base image	It carries the login, storage, security and Notebook Intelligence wiring. RPAdmin checks this and rejects any other base.
The platform builds and stores the image, not your laptop	Nobody holds cloud push credentials; the build runs in GitLab and lands in the project's own private registry space.
A project admin (PI) registers the image in RPAdmin	Registration validates the image and pins the exact version. Up to 10 images per project.
Members see their own project's images only	Plus the platform defaults, always.

How it works, in four steps

Step 1 — Ask for your project's image space (once)

Email support@sciencecloud.nasa.gov with your project key and ask to enable custom images. The platform team creates the project's registry space and gives your PI access to the rp-project-images GitLab project. This is a one-time step per project.

Step 2 — Write the Dockerfile

In the GitLab project rp-project-images, your project has a folder projects/<project_key>/ with a Dockerfile.template. Rename it to Dockerfile and add your packages below the FROM line. Do not change the FROM line.

FROM 194417786090.dkr.ecr.us-west-2.amazonaws.com/rp/notebook-base:latest

# --- project-specific additions below -------------------------------
RUN pip install --no-cache-dir xarray==2026.1.0 rioxarray
RUN mamba install --yes -c conda-forge gdal && mamba clean --all -f -y

Open a merge request. The reviewer checks that the change touches only your project's folder.

Step 3 — The platform builds it

When the merge request is merged, the pipeline builds the image and stores it in your project's registry space with a tag like 20260923-a1b2c3d. The job log prints the repository, the tag and the digest. Copy the repository and tag.

Step 4 — Register it in RPAdmin

Your PI opens RPAdmin, goes to the project page, and in Spawn Images adds the repository and tag with a display name your members will recognise (for example "Hydrology stack, Sept 2026").

RPAdmin then:

checks that the image exists and lives in your project's registry space;
checks, layer by layer, that it was built on the platform base image;
pins the exact version (the digest), so a later rebuild never silently changes what members run.

If any check fails, RPAdmin says which one. The most common message is base_not_inherited: the FROM line was changed.

Using it

On the launch page, pick your project first. The Images list then shows the platform defaults plus your project's images by display name. Pick yours and start the server. See The tools inside JupyterLab — a reference for the rest of the launch page.

Updating or retiring an image

New version: change the Dockerfile, merge, and register the new tag. Keep the old one until members have switched, then remove it. Each project can hold up to 10 images.
Something is wrong with an image: your PI can switch it off in RPAdmin without deleting it. It disappears from the launch page at once. Platform admins can do the same for any image.
Rebuilding does not move anyone. Registered images are pinned by digest, so a member's server always runs the exact version that was validated.

Common questions

Can I use an image from Docker Hub or my own registry? No. Only images built by the platform pipeline, on the platform base, can be registered. The free-text "Other image" box on the launch page is gone for the same reason.

Does a custom image cost more? No. You pay for server time as before. The image itself is stored in the platform's registry at no charge to the project.

Who can register images? The project's PI, or a platform admin. Other members can see the list in RPAdmin but not change it.

How big can the image be? There is no hard limit, but a large image starts slowly: every extra gigabyte is pulled onto the machine before your server opens. Install what you need, and clean package caches in the same RUN line.

Need help?

Email support@sciencecloud.nasa.gov.