Skip to content

Commit

Permalink
Remove anything Docker related from the README (#1158)
Browse files Browse the repository at this point in the history
* Remove anything Docker related from the README

* Add more detailed instructions for conda setup for ark

* Include section on updating the repo

---------

Co-authored-by: Alex Kong <alkong@stanford.edu>
  • Loading branch information
alex-l-kong and Alex Kong authored Oct 4, 2024
1 parent cb8ccdb commit 9dab65b
Showing 1 changed file with 44 additions and 23 deletions.
67 changes: 44 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

| | |
| --- | --- |
| CI / CD | [![CI](https://github.com/angelolab/ark-analysis/actions/workflows/ci.yml/badge.svg)](https://github.com/angelolab/ark-analysis/actions/workflows/ci.yml) ![Read the Docs](https://img.shields.io/readthedocs/ark-analysis) [![Coverage Status](https://coveralls.io/repos/github/angelolab/ark-analysis/badge.svg?branch=main)](https://coveralls.io/github/angelolab/ark-analysis?branch=main) ![Docker Image Version (latest by date)](https://img.shields.io/docker/v/angelolab/ark-analysis?arch=amd64&color=%23469ae5&label=Docker%20Version&sort=date) |
| CI / CD | [![CI](https://github.com/angelolab/ark-analysis/actions/workflows/ci.yml/badge.svg)](https://github.com/angelolab/ark-analysis/actions/workflows/ci.yml) ![Read the Docs](https://img.shields.io/readthedocs/ark-analysis) [![Coverage Status](https://coveralls.io/repos/github/angelolab/ark-analysis/badge.svg?branch=main)](https://coveralls.io/github/angelolab/ark-analysis?branch=main) |
| Package | [![PyPI - Version](https://img.shields.io/pypi/v/ark-analysis.svg?logo=pypi&label=PyPI&logoColor=gold)](https://pypi.org/project/ark-analysis/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/ark-analysis.svg?color=blue&label=Downloads&logo=pypi&logoColor=gold)](https://pypi.org/project/ark-analysis/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ark-analysis.svg?logo=python&label=Python&logoColor=gold)](https://pypi.org/project/ark-analysis/) |
|Meta | [![PyPI - License](https://img.shields.io/pypi/l/ark-analysis?color=9400d3)](LICENSE) |

Expand All @@ -25,9 +25,9 @@ Full documentation for the project can be found [here](https://ark-analysis.read
- [5. Spatial analysis](#5-spatial-analysis)
- [Installation Steps.](#installation-steps)
- [Download the Repo](#download-the-repo)
- [Setting up Docker](#setting-up-docker)
- [Running on Windows](#running-on-windows)
- [Using the Repository (Running the Docker)](#using-the-repository-running-the-docker)
- [Using the Repository](#using-the-repository)
- [Updating the repo](#updating-the-repo)
- [External Tools](#external-tools)
- [Mantis Viewer](#mantis-viewer)
- [Mantis directory structure](#mantis-directory-structure)
Expand Down Expand Up @@ -112,47 +112,68 @@ cd ark-analysis
conda env create -f environment.yml
```

#### Setting up Docker

There is a complementary [setup video](https://youtu.be/EXMGdi_Izdw).

Next, you'll need to download Docker Desktop:
- First, [download](https://hub.docker.com/?overlay=onboarding) Docker Desktop.
- Once it's successfully installed, make sure it is running by looking in toolbar for the Docker whale icon.


#### Running on Windows

Our repo runs best on Linux-based systems (including MacOS). If you need to run on Windows, please consult our [Windows guide](https://ark-analysis.readthedocs.io/en/latest/_rtd/windows_setup.html) for additional instructions.

#### Using the Repository (Running the Docker)
#### Using the Repository

Enter the following command into terminal from the same directory you ran the above commands:
First, activate the `conda` environment inside the root of the `ark-analysis` folder:

```sh
./start_docker.sh
```

If running for the first time, or if our Docker image has updated, it may take a while to build and setup before completion.
conda activate ark_env
```

This will generate a link to a Jupyter notebook. Copy the last URL (the one with `127.0.0.1:8888` at the beginning) into your web browser.
Once activated, notebooks can be used via this command for Windows:

Be sure to keep this terminal open. **Do not exit the terminal or enter `control-c` until you are finished with the notebooks**.
```sh
start_jupyter.sh
```

**NOTE:**
or this command for macOS:

If you already have a Jupyter session open when you run `./start_docker.sh`, you will receive a couple additional prompts.
```sh
./start_jupyter.sh
```

Copy the URL listed after `Enter this URL instead to access the notebooks:`
This will automatically open your browser with a link to our Jupyter notebooks.

You will need to authenticate. Note the last URL (the one with `127.0.0.1:8888` at the beginning), copy the token that appears there (it will be after `token=` in the URL), paste it into the password prompt of the Jupyter notebook, and log in.
Be sure to keep this terminal open. **Do not exit the terminal or enter `control-c` until you are finished with the notebooks**.

You can shut down the notebooks and close docker by entering `control-c` in the terminal window.

**REMEMBER TO DUPLICATE AND RENAME NOTEBOOKS**

If you didn't change the name of the notebooks within the `templates` folder, they will be overwritten when you decide to update the repo. Read about updating Ark [here](#updating-the-repository)

### Updating the repo

The `ark-analysis` repo is constantly being updated. In order to get those changes to your version, you'll need to tell git to update with the following command:

```
git pull
```

After performing the above command, you will sometimes need to update your environment:

```shell
conda remove --name ark_env --all
conda env create -f environment.yml
```

To update the notebooks, run this command for Windows:

```shell
start_jupyter.sh -u
```

or this command for macOS:

```shell
./start_jupyter.sh -u
```

## External Tools

### Mantis Viewer
Expand Down

0 comments on commit 9dab65b

Please sign in to comment.