Update readme #1010
Update readme #1010
Conversation
Some notes for people that might want to run full-on native, with detail about how Mac hijacks port 7000 and how to get around it.
This reverts commit 096887c.
Some details for user that might be running Python3, Mac, and want to run everything locally/natively.
WalkthroughWalkthroughThe recent updates provide comprehensive instructions for setting up and running the application locally, addressing both the installation requirements and configuration steps necessary for Keycloak, the frontend, and testing procedures. Additionally, the updates highlight a potential issue with port conflicts on Mac OS 12.1 and enhance the understanding of the system. Moreover, there's an important note on the backend regarding the preferred MySQL library for Python 3 environments outside Docker. Changes
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (invoked as PR comments)
Additionally, you can add CodeRabbit Configration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Review Status
Actionable comments generated: 3
Configuration used: .coderabbit.yaml
Files selected for processing (2)
- README.md (4 hunks)
- spiffworkflow-backend/src/spiffworkflow_backend/init.py (1 hunks)
Additional comments: 2
README.md (2)
- 28-32: The guidance to modify
__init__.pyby addingpymysqlas a replacement forMySQLdbis crucial for Python 3 users. Ensure that the instructions are consistent with the actual changes made in the__init__.pyfile of thespiffworkflow-backendproject.- 74-74: The additional note in the Docker section about MacOS 12.1 and AirPlay receiver port conflicts reinforces the importance of this information. Ensure this advice is consistent and clear across different sections where port conflicts are mentioned.
| ## If you want to run all locally: | ||
|
|
||
| If you're on a Mac and trying to run native (might translate elsewhere) running python 3 and get errors with mysqlclient and psycopgen2 when running the Poetry install, you may need to install mysql-client, pkg-config, mysqlclient, and psycopgen2 first, remove mysqlclient and psycopgen2 from the pyproject.toml (or Poetry will try to build them and crash), and run the Poetry install again. | ||
|
|
||
| brew install mysql-client pkg-config | ||
| export PKG_CONFIG_PATH="$(brew --prefix)/opt/mysql-client/lib/pkgconfig" | ||
| pip install mysqlclient | ||
| pip install psycopg2 | ||
|
|
||
| Python3 also won't recognize MySQLdb as a module. After the above installs (which you would do pre-Poetry), add these lines to __init__.py in the backend project: | ||
|
|
||
| import pymysql; | ||
| pymysql.install_as_MySQLdb() | ||
|
|
||
| On a Mac, port 7000 (used by the app) might be hijacked by Airplay. See the Docker section below. | ||
|
|
||
| Remember, if you don't need a full-on native dev experience, you can run the docker image, which saves you from all the native setup. |
There was a problem hiding this comment.
The instructions for resolving issues with mysqlclient and psycopg2 during the Poetry install are clear but consider adding a note about the potential need for these steps only if errors are encountered. This could prevent unnecessary pre-emptive modifications to pyproject.toml.
| import pymysql; | ||
| pymysql.install_as_MySQLdb() | ||
|
|
||
| On a Mac, port 7000 (used by the app) might be hijacked by Airplay. See the Docker section below. |
There was a problem hiding this comment.
The note about port 7000 potentially being used by AirPlay on Mac is helpful. Consider adding a command or step-by-step guide on how to check if the port is currently in use, providing a more complete solution to the problem.
| # This is necessary to make sure that the pymysql library is used as the MySQLdb library | ||
| # This is only needed if you want to run non-docker local and are using Python 3. | ||
| # See the repo's top-level README for details. | ||
| # import pymysql; | ||
| # pymysql.install_as_MySQLdb() |
There was a problem hiding this comment.
The comments explaining the use of pymysql as a replacement for MySQLdb are commented out. If these instructions are meant to be followed by users, consider moving this guidance to the README.md or ensuring it's uncommented and executed as part of the application setup.
For users that want to run on a Mac, Python3, and everything local/native, they'll need these notes and the code tweak in init.py
Summary by CodeRabbit