karakanb opened a new issue #19566: URL: https://github.com/apache/airflow/issues/19566
### Describe the issue with documentation I followed the documentation about running Breeze to develop locally. I have set up the database properly, and all the containers are properly starting with Breeze. I am on a Macbook Pro 13-inch, 2020. This machine has 16GB RAM, and I have allocated 6GB RAM and 3CPUs to the Docker VM. I am using Docker for all my development work, so I am familiar with it. The final view I get is here: <img width="1440" alt="image" src="https://user-images.githubusercontent.com/16530606/141528323-2b6327b1-af38-400f-8980-9bc94fa2222b.png";> The `yarn` step on the top right takes ~630 seconds on my machine, I guess a lot of it comes from the fact that the Docker networking is pretty bad on macOS due to the VM. Anyway, when I go to `localhost:28080`, I am getting a lot of 404s with CSS and JS files. <img width="1440" alt="image" src="https://user-images.githubusercontent.com/16530606/141528396-5036f017-1281-4be4-aade-acc82d0627ab.png";> Obviously, this breaks the UI. While going through the logs, I notice that there's a notice there: ``` WARNING: It seems that the generated assets files do not match the content of the sources ``` Okay, cool. I stop the Breeze environment, run the command `./airflow/www/compile_assets.sh` and I have my assets generated quite quickly for me, nice. I start Breeze again. The logs don't complain about the assets not matching. There's a weird problem now: - The yarn command takes a long time, and that's fine. - While waiting for that to finish, refreshing the page makes everything look fine. - Although some icons are not loading, and the multi-select tags like the ones in the role create UI are not working, and there are still 404s in the network tab. - I wait until the yarn command finishes. - The UI is back to being completely broken. I presume there's something wrong with the yarn command that breaks the assets. One of the files that seems to be missing is a file called `ab.js`. I am searching my airflow folder for that to find a file with that name using `find . -name 'ab.js'`, but nothing matches. On the top left corner, I try to recompile the assets, this time inside the container, using the command `./airflow/www/compile_assets.sh`. This command takes ~80 seconds, and finishes. Now when I refresh the UI, it is partially back again: <img width="1440" alt="image" src="https://user-images.githubusercontent.com/16530606/141531523-650fdd17-742b-4ba0-891a-369304f37145.png";> At this point, I have no clue about what to fix or how to fix. ### How to solve the problem - I think the documentation has wrong levels of titles that makes it confusing to know what steps are alternatives to each other, and what are "must do" steps. - Docker Compose and pyenv are stated as alternatives to each other in "Note to Starters" section of the Contributers Quick Start guide, but then the prerequisites section for Ubuntu tells them in order as if both are required. - It might be the case that pyenv is still required for Docker-based setup, and that's also fine, but it is not clear if I have to do that, so I skipped that because I assumed everything regarding Airflow and its dependencies would be covered by Docker containers instead of having a local environment. - Similarly, the same document is instructing to install `jq` without any usage of it. I agree that jq is an amazing tool and a must-have for many people, but if it is not relevant for this setup, why have it? - It might be the case that the installation script or Breeze requires it for some reason, but it'd be good to see this mentioned. - Also, if Breeze depends on it, why does it not check if it exists, just like it checks for Docker versions? - The quick start guide has pretty similar steps for VS Code and PyCharm separately, which makes the document confusing. - I love the fact that there are specific instructions for both of the IDEs in the document, but are they really relevant for setting up the environment? - I think the primary focus of the document should be to get a contributor having their first local change and being able to see it over localhost. - Once this is achieved, the suggestions and instructions for each IDE could focus on improving the developer ergonomics. - As simple as it is, as a new contributor, I should be able to run Breeze, pick up `vim` or `nano` or whatever editor I want, edit an HTML file or a Python file somewhere, and immediately see the result of this in my browser over localhost. - After this, I'd obviously love to see what debugging opportunities does VS Code or PyCharm offer, but not before I have stuff running. - Also, the same confusion about Docker vs pyenv continues under these sections as well. - For example, why does the section on VS Code have a subsection titled as "Installing airflow in the local virtual environment airflow-env with breeze."? - At this point, I have my containers running, and all the commands on the container have completed successfully, but there are still some assets missing in my setup. - Did I need to run something else? ### Anything else Maintaining a project sometimes makes it harder to notice what are the things the new joiners might be going through, therefore I wanted to share my findings as a first-time contributor so that maybe we can identify areas for improvement. Once I have my environment working locally, I would love to contribute to the documentation with my findings. I appreciate all the docs there so far, and I acknowledge that the fact that I couldn't get this to work is probably because I missed some step somewhere or made a mistake down the line, but I'd also like to make it as foolproof as possible so that someone like me could still make it work and hopefully contribute to Airflow. ### Are you willing to submit PR? - [X] Yes I am willing to submit a PR! ### Code of Conduct - [X] I agree to follow this project's [Code of Conduct](https://github.com/apache/airflow/blob/main/CODE_OF_CONDUCT.md) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
![https://user-images.githubusercontent.com/16530606/141528323-2b6327b1-af38-400f-8980-9bc94fa2222b.png"](https://user-images.githubusercontent.com/16530606/141528323-2b6327b1-af38-400f-8980-9bc94fa2222b.png"){kind=link}
![https://user-images.githubusercontent.com/16530606/141528396-5036f017-1281-4be4-aade-acc82d0627ab.png"](https://user-images.githubusercontent.com/16530606/141528396-5036f017-1281-4be4-aade-acc82d0627ab.png"){kind=link}
![https://user-images.githubusercontent.com/16530606/141531523-650fdd17-742b-4ba0-891a-369304f37145.png"](https://user-images.githubusercontent.com/16530606/141531523-650fdd17-742b-4ba0-891a-369304f37145.png"){kind=link}