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.

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

📝 Update local-setup-ui.md #6

Merged
merged 14 commits into from
Oct 1, 2024
Merged
Changes from 13 commits
Commits
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
80 changes: 56 additions & 24 deletions docusaurus-docs/community/contribute/local-setup-ui.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,46 +9,78 @@ To get started with conda-store-ui development, there are a couple of options. T

## Pre-requisites
Copy link
Owner

@pavithraes pavithraes Sep 17, 2024

Choose a reason for hiding this comment

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

If it's Ok with you, I might update this section in my pull request to point to the page that outlines the git cloning & branching workflow: https://github.com/pavithraes/conda-store/blob/contrib-docs/docusaurus-docs/community/contribute/contribute-code.md#setup-for-local-development

Copy link
Author

Choose a reason for hiding this comment

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

That almost makes sense to me, but I'm not sure where/how Docker fits into this suggestion. Should we move the Docker installation instructions out of the core, ui, and juptyerlab-extension docs and into the contribute-code doc?

Copy link
Owner

Choose a reason for hiding this comment

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

I think we can keep Docker here, and only remove the git & GitHub specific instructions in favour of the above doc

Copy link
Author

Choose a reason for hiding this comment

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

Sounds good 👍


We use [Docker Compose](https://docs.docker.com/compose/) to set up the infrastructure before starting ensure that you have Docker compose installed. If you need to install docker-compose, please see their [installation documentation](https://docs.docker.com/compose/install/)
This document assumes that you have the following tools set up on your computer:

1. Fork and clone the [conda-store-ui](https://github.com/conda-incubator/conda-store-ui.git) repository.
2. Copy `.env.example` to `.env`. All default settings should work, but if you want to test against a different version of conda-store-server, you can specify it in the `.env` file by setting the `CONDA_STORE_SERVER_VERSION` variable to the desired version
- Docker Compose (which requires Docker)
- Git

## Docker (Recommended)
You also need to have:

Once you have a [local copy of the `conda-store` repository](community/contribute/contribute-code#setup-for-local-development)
- A GitHub.com account

Running conda-store-ui in Docker is the simplest way to set up your local development environment.
Once you have all of those things, then you need to:

1. Run `yarn run start:docker` to start the entire development stack.
Open your local browser and go to [http://localhost:8000](http://localhost:8000) so see conda-store-ui.
3. You can then log in using the default username of `username` and default password of `password`.
1. [Fork the conda-store-ui repository](https://github.com/conda-incubator/conda-store-ui/fork)
2. `git clone` the fork to your computer.

**Note:** Hot reloading is enabled, so when you make changes to source files, your browser will reload and reflect the changes.
## Basic Option (recommended): Run the UI in Docker

## Without Docker
For basic local development on the UI, running conda-store-ui in Docker is the simplest way to get started.

This setup still uses Docker for supporting services but runs conda-store-ui locally.
1. Change your working directory to the project root: `cd conda-store-ui`
2. Optional. Set environment variables. Copy `.env.example` to `.env`. All default settings should work, but if you want to test against a different version of conda-store-server, you can specify it in the `.env` file by setting the `CONDA_STORE_SERVER_VERSION` variable to the desired version. If you skip this step, it will be done automatically for you.
3. Run `docker compose --profile local-dev up --build` to start the entire development stack. This step may take a few minutes the first time you run it.
4. Open your local browser and go to [http://localhost:8000](http://localhost:8000) to see conda-store-ui.
5. You can then log in using the default username of `username` and default password of `password`.

### Set up your environment
:::note

Hot reloading is enabled, so when you make changes to source files (i.e., files under the conda-store-ui/src/ directory), your browser will reload and reflect the changes.

:::

## Advanced Option: Run the UI locally (with the rest of the stack in Docker)

For more advanced development on conda-store-ui, the first option might not be sufficient. If you need to work extensively in the UI codebase, then you will probably want to run the UI web app locally rather than within a Docker container.

:::note

this setup still uses Docker to run the rest of the Conda Store stack. That means that the Conda Store database, server, worker, and storage services will all run in Docker containers. However, the frontend web app (conda-store-ui) will run locally (not in a Docker container) with this setup.
gabalafou marked this conversation as resolved.
Show resolved Hide resolved

:::

### Set up your Conda environment

This project uses [Conda](https://conda.io) for package management. To set up Conda, please see their [installation documentation](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html).
1. Change to the project root ` cd conda-store-ui`
2. From the project root create the conda environment `conda env create -f environment_dev.yml`
3. Activate the development environment `conda activate cs-ui-dev-env`
4. Install yarn dependencies `yarn install`

### Run the application
1. Change to the project root: `cd conda-store-ui`
2. From the project root, create the conda environment: `conda env create -f environment_dev.yml`
gabalafou marked this conversation as resolved.
Show resolved Hide resolved

### Run conda-store-ui locally (and the rest of the stack in Docker)

:::tip

Make sure you are in the project root: `cd conda-store-ui`

:::

1. Activate the development environment: `conda activate cs-ui-dev-env`
2. Set environment variables: copy `.env.example` to `.env`. All default settings should work, but if you want to test against a different version of conda-store-server, you can specify it in the `.env` file by setting the `CONDA_STORE_SERVER_VERSION` variable to the desired version.
3. Run: `corepack enable`. Corepack comes with Node.js which was installed when you set up your Conda dev environment. Running `corepack enable` ensures that the version of Yarn that you use in the next step matches the version required by the repo (see package.json > packageManager). Yarn also comes with Node.js but is not automatically added to your environment's path until you run `corepack enable`.
4. Install/update JavaScript dependencies: `yarn install`
5. Run `yarn run start` and wait for the application to finish starting up. This command will run a local dev server for the UI app and run the other Conda Store services in Docker.
6. Open your local browser and go to [http://localhost:8000](http://localhost:8000) to see conda-store-ui.
7. You can then log in using the default username of `username` and default password of `password`.

:::note

1. Run `yarn run start` and wait for the application to finish starting up
Open your local browser and go to [http://localhost:8000](http://localhost:8000) so see conda-store-ui.
3. You can then log in using the default username of `username` and default password of `password`.
Hot reloading is enabled, so when you make changes to source files, your browser will reload and reflect the changes.

**Note:** Hot reloading is enabled, so when you make changes to source files, your browser will reload and reflect the changes.
:::

## Run the test suite
### Run the test suite

We currently use jest in order to run unit tests.
If you chose the advanced option for local development, you will be able to run the tests locally. We currently use Jest in order to run unit tests.

```bash
yarn test // find every test with the .test.[tsx|ts] extension
Copy link

Choose a reason for hiding this comment

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

yarn is also still used down here. Not sure about getting rid of all mention of installing yarn?

Copy link

Choose a reason for hiding this comment

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

If one creates the conda environment per the instructions above yarn should be already installed

Copy link
Author

Choose a reason for hiding this comment

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

This section should probably somehow be moved into Advanced development then.

Expand Down