Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docs for using images outside Fornax #39

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add docs for using images outside Fornax #39

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
59f7db2
Add docs for using images outside fornax
zoghbi-a Aug 23, 2024
2db1952
change the image from tractor-develop to tractor-stable since this is…
zoghbi-a Sep 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -227,6 +227,36 @@ Software is installed in miniconda environments. You can use "[conda list](http
### How can I contribute to existing Open-Source Fornax notebook tutorials?
* open issue or PR on Fornax Github [repo](https://github.com/nasa-fornax/fornax-demo-notebooks)

## Using Fornax Software Environments Outside Fornax
The Fornax software environments are available as docker container images. To use them on your computer, you will need to install
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we add an example motivation?

"If you want to run the Fornax software Environment outside of the Fornax Science Console, that is an available option. Possible use cases for this are if you want to use different CPU/GPU/RAM/storage options than are available to you for free on the Fornax system. Possibly you have your own compute or your own cloud based account" The advantage of using our Software environment is that it is maintained already for you with widely used Astronomy software.

[docker](https://docs.docker.com/engine/install/). The following are the steps needed to run the notebooks locally using the Fornax images:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did this years ago and it was a somewhat involved process. If this is still the case, maybe a warning is in order for users so that they know this is not some simple 'pip install Docker'. Maybe something like " You can expect this will take ~N - N minutes and N Mb of space on your personal computer"


- Start in a empty working direcotry that will be used used for the notebooks and any data generated during the analysis:
```sh
mkdir work
cd work
```
- Clone the notebook repo: `git clone https://github.com/nasa-fornax/fornax-demo-notebooks.git`.
- Download the relevant Fornax image. In this case, we are using the `tractor-stable` image. `docker pull public.ecr.aws/f6e2z3b0/fornax-images:tractor-stable`.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the name of this image 'tractor-stable' going to always be the same name in perpetuity, or will the names change? If the names will change, or if we want users to be able to see multiple different environments, then can you teach us users how to figure out the full list of available images? as well as corresponding addresses for those images (ie., is the 'f6e2...' the same for all images?

- Run the image with:
```
docker run --rm -p 8888:8888 \
-v $(pwd):/opt/workspace:rw \
-w /opt/workspace \
--user root -e NB_UID=$(id -u) -e NB_GID=$(id -g) \
-e CHOWN_HOME=yes -e CHOWN_HOME_OPTS='-R' \
public.ecr.aws/f6e2z3b0/fornax-images:tractor-stable \
start-notebook.sh --NotebookApp.token=''
```

This will launch Jupyterlab inside the container. You can access it by going to `http://127.0.0.1:8888/lab` in your browser.
the `-v` option mounts the `work` folder directory as `/opt/workspace` inside the container. The `-w` options sets `/opt/workspace`
as the working directory when jupyterlab launches. The next two lines ensures the right write permission are set so you can edit
the notebooks and save the results.

Any files edited or created under `/opt/workspace` will be available outside the container in the `work` directory.
Any other files or changes will disapper once the running container is stopped.

## Troubleshooting
* If my internet connection goes away or is intermittent - what happens to the running notebook?
* Restart kernel will solve some problems, especially if the cells were run out of order
Expand Down