📝 Update local-setup-ui.md

[gabalafou]

This is a pull request on top of a pull request: conda-incubator#763.

Related: conda-incubator/conda-store-ui#415.

Kim and Gabriel had a meeting and came up with ideas to make the instructions clearer.

[gabalafou]

@kcpevey, I would appreciate if you could check that this PR matches what we discussed in our meeting, as well as spotting if you see any further room for improvement.

@pavithraes, I would appreciate if you could also review the PR so that it aligns with your vision and your base PR, conda-incubator#763.

[kcpevey]

This looks great! Thanks @gabalafou

[trallard]

The first part of this PR says no matter what approach one follows one must install Docker/Docker compose. But then the advance section does not use Docker at all.
Should the Docker install requirements be only needed for container-based development?

Also we should note as requirements installing Docker as it's needed to be able to use Docker compose (right now the only req is Docker compose)

[gabalafou]

The first part of this PR says no matter what approach one follows one must install Docker/Docker compose. But then the advance section does not use Docker at all.

Heh, this document is starting to feel cursed lol. Both approaches use Docker Compose, but somehow we're failing to communicate all of this in a clear fashion.

The relevant package.json scripts are:

# BASIC
"start:docker": "docker compose --profile local-dev up --build",

# ADVANCED
"start": "yarn run start:services && yarn run start:ui",
"start:services": "docker compose up -d",

The setup labeled "basic" uses start:docker, which in turn calls docker compose and puts everything in Docker, including conda-store-ui. The setup labeled "advanced" uses yarn start which in turn calls start:services which in turn also calls docker compose but runs everything except the conda-store-ui app in a Docker container.

Also we should note as requirements installing Docker as it's needed to be able to use Docker compose (right now the only req is Docker compose)

The installation page for Docker Compose is pretty explicit about needing both Docker Engine and Docker CLI installed in order to use Docker Compose. Also, Docker Compose comes bundled with Docker Desktop for Linux, Mac, and Windows. So I'm not sure how mentioning Docker here as a requirement helps.

Would it be better instead to tell people to install Docker Desktop?

[trallard]

This is the part that is confusing in the docs as is

For many Conda Store UI development tasks, the basic setup should work. But if you need to work extensively in the UI codebase, then you will probably want to run the conde-store-ui app locally rather than within a Docker container.

So this points to a workflow where one would use a local runtime vs a container.

Indicating that Docker is a requirement is good, since not everyone installs Docker compose from Docker desktop.

[kcpevey]

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

[trallard]

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

[gabalafou]

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

[trallard]

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

[pavithraes]

This looks great, thank you!

[pavithraes]

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

[gabalafou]

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?

[pavithraes]

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

[gabalafou]

Sounds good 👍

[trallard]

This is much better now thanks @gabalafou

[gabalafou]

I actually realized that this PR does not really depend on conda-incubator/conda-store-ui#415 so I am going to remove that sentence from the PR description.

The instructions in this PR will be wrong if PR 415 is not merged, but they will be wrong in exactly the same way that the current instructions in the docs are wrong. Which is to say, the current instructions for Docker-based dev are missing a yarn install step that really shouldn't be needed but there was a misconfiguration of the Docker Compose file that PR 415 fixes. (For a longer explanation, read the description in conda-incubator/conda-store-ui#415.)

[pavithraes]

Got it. This PR is also being merged into another PR, and not the main branch directly. I think we can merge now :)