openoakland/woeip

As a new volunteer, I'd like to have clear instructions for installing the WOAQ application locally

mnorelli opened this issue · 4 comments

mnorelli commented

Describe the bug
The README instructions are still confusing to new volunteers and mix together the Docker method with the command line git and npm method for installing the app.

Expected behavior
A newcomer of any comfort level with Docker and git and npm should be able to follow the README step-by-step and get (a) a working app running locally, and (b) know how to make edits to the code and submit changes.

Desktop (please complete the following information):

  • OS: Mac and Windows

Labels

  • Add a status label
    • needs definition
    • needs help
    • ready to work on
    • in progress
    • backlog
  • Add a bug label
  • Add additional labels as needed

Affected Components (For Developers)
None

Technical Resources (For Developers)
Install Node

exchrotek commented

@mnorelli by any chance do you know what some of the common pitfalls or obstacles newcomers encounter during installation & deployment of the WOAQ web app locally?

I remember at one point when you first started, the port # for Docker you had to deviate from the instructions in order to get it working (correct me if I'm misremembering), but was there anything else you faced that you'd like to share?

Not sure why I can't tag Gabriel in here, but since he went thru the process just very recently, any feedback he can add to this ticket as well would be great!

mnorelli commented

@theecrit had some challenges, Anna and Frances asked me some questions about it, and Gabriel (these three folks are not joined to GitHub) and I had the question about whether npm was needed if Docker was successful. In my case, I had an old project that was using port 3000; I just needed to kill that process for Docker to complete, so that issue was particular to me.

I had the sense that we could be more comprehensive and clear in guiding people toward making a contribution. @theecrit invited me to the GitHub project when I was ready to submit code, but I guess even that could be added to the onboarding process as a step, as well.

gsehrlich commented

Two comments based on my experience. 1. On my machine, Docker came with Docker Compose, so we might want to clarify that the latter is sometimes (or always?) a redundant instruction. 2. There's no need to run npm install, since Docker is doing that. Everything else worked perfectly for me!

mnorelli commented

Add text about memory requirements for Docker, per Anna's experience.