update local dev setup docs (#1015)
Co-authored-by: burnettk <burnettk@users.noreply.github.com>
This commit is contained in:
Kevin Burnett
GitHub
parent
223ff95014
commit
04f8f2b0ac
49
README.md
49
README.md
|
|
@ -7,53 +7,49 @@ Using tools that look a lot like flow-charts and spreadsheets, it is possible to
|
|||
Please visit the [SpiffWorkflow website](https://www.spiffworkflow.org) for a [Getting Started Guide](https://www.spiffworkflow.org/posts/articles/get_started/) to see how to use SpiffArena and try it out.
|
||||
There are also additional articles, videos, and tutorials about SpiffArena and its components, including SpiffWorkflow, Service Connectors, and BPMN.js extensions.
|
||||
|
||||
## Backend Setup
|
||||
|
||||
First install python, poetry, and mysql. Then:
|
||||
|
||||
## Backend Setup, local
|
||||
|
||||
Remember, if you don't need a full-on native dev experience, you can run with docker (see below), which saves you from all the native setup.
|
||||
If you have issues with the local dev setup, please consult [the troubleshooting guide](https://spiff-arena.readthedocs.io/en/latest/Support/Running_Server_Locally.html).
|
||||
|
||||
There are three prerequisites for non-docker local development:
|
||||
|
||||
1. python - [asdf-vm](https://asdf-vm.com) works well for installing this.
|
||||
2. poetry - `pip install poetry` works
|
||||
3. mysql - the app also supports postgres. and sqlite, if you are talking local dev).
|
||||
|
||||
When these are installed, you are ready for:
|
||||
|
||||
cd spiffworkflow-backend
|
||||
poetry install
|
||||
./bin/recreate_db clean
|
||||
./bin/run_server_locally
|
||||
|
||||
## If you want to run all locally:
|
||||
On a Mac, port 7000 (used by the backend) might be hijacked by Airplay. For those who upgraded to MacOS 12.1 and are running everything locally, your AirPlay receiver may have started on Port 7000 and your server (which uses port 7000 by default) may fail due to this port already being used. You can disable this port in System Preferences > Sharing > AirPlay receiver.
|
||||
|
||||
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.
|
||||
|
||||
## Keycloak Setup
|
||||
|
||||
You will want an openid server of some sort.
|
||||
There is one built in to the app that is used in the docker compose setup for simplicity, but non-compose defaults use a separate keycloak container by default.
|
||||
You will want an openid server of some sort for authentication.
|
||||
There is one built in to the app that is used in the docker compose setup for simplicity, but this is not to be used in production, and non-compose defaults use a separate keycloak container by default.
|
||||
You can start it like this:
|
||||
|
||||
./keycloak/bin/start_keycloak
|
||||
|
||||
It'll be running on port 7002 (if you want to log into the keycloak admin, localhost:7002).
|
||||
Creds = admin/admin (also logs you into the app if running the front end)
|
||||
It'll be running on port 7002
|
||||
If you want to log in to the keycloak admin console, it can be found at http://localhost:7002, and the creds are admin/admin (also logs you in to the app if running the frontend)
|
||||
|
||||
## Frontend Setup
|
||||
## Frontend Setup, local
|
||||
|
||||
First install nodejs, ideally the version in .tool-versions (but likely other versions will work). Then:
|
||||
First install nodejs (also installable via asdf-vm), ideally the version in .tool-versions (but likely other versions will work). Then:
|
||||
|
||||
cd spiffworkflow-frontend
|
||||
npm install
|
||||
npm start
|
||||
|
||||
Assuming you're running KeyCloak as indicated above, login will be admin/admin.
|
||||
Assuming you're running Keycloak as indicated above, you can log in with admin/admin.
|
||||
|
||||
## Run tests
|
||||
|
||||
|
|
@ -71,8 +67,6 @@ For full instructions, see [Running SpiffWorkflow Locally with Docker](https://w
|
|||
|
||||
The `docker-compose.yml` file is for running a full-fledged instance of spiff-arena while `editor.docker-compose.yml` provides BPMN graphical editor capability to libraries and projects that depend on SpiffWorkflow but have no built-in BPMN edit capabilities.
|
||||
|
||||
Note: For those who upgraded to MacOS 12.1 and are running everything locally, your AirPlay receiver may have started on Port 7000 and your docker (or anything requesting port 7000) may fail due to this port already being used. You can disable this port in System Preferences > Sharing > AirPlay receiver.
|
||||
|
||||
## Contributing
|
||||
|
||||
To start understanding the system, you might:
|
||||
|
|
@ -97,4 +91,3 @@ SpiffArena's main components are published under the terms of the
|
|||
|
||||
You can find us on [our Discord Channel](https://discord.gg/BYHcc7PpUC).
|
||||
Commercial support for SpiffWorkflow is available from [Sartography](https://sartography.com).
|
||||
|
||||
|
|
|
|||
|
|
@ -38,15 +38,32 @@ For a potentially faster setup:
|
|||
|
||||
- Use the provided commands to run the server with Docker Compose.
|
||||
|
||||
### 4. Access Hosted Version of Spiff
|
||||
### 4. Mac install issues
|
||||
Please follow the README.md at the root of the spiff-arena repo first.
|
||||
If you're on a Mac and trying to run natively (it might translate elsewhere) and get errors when running `poetry install`, many of the issues are related to relational database engine libraries.
|
||||
You will find lots of people having pain related to these on the internet, so hopefully the solution to your particular problem is easy to find, but this is not always the case.
|
||||
You may need to install additional system dependencies.
|
||||
|
||||
brew install mysql-client pkg-config
|
||||
export PKG_CONFIG_PATH="$(brew --prefix)/opt/mysql-client/lib/pkgconfig"
|
||||
pip install mysqlclient
|
||||
pip install psycopg2
|
||||
|
||||
One person decided that mysqlclient and psycopg2 were more trouble than they were worth and removed them from the pyproject.toml, while doing `poetry add pymysql` instead.
|
||||
If you are using mysql, psycopg2 is not necessary, and pymysql is a pure python implementation of the MySQL client library.
|
||||
In that case, python won't recognize MySQLdb as a module, so after the above installs (which you would do pre-Poetry), add these lines to __init__.py in the backend project:
|
||||
|
||||
```python
|
||||
import pymysql;
|
||||
pymysql.install_as_MySQLdb()
|
||||
```
|
||||
### 5. Access Hosted Version of Spiff
|
||||
|
||||
If you prefer not to install anything locally:
|
||||
|
||||
- Navigate to [https://www.spiffworkflow.org/posts/articles/get_started](https://www.spiffworkflow.org/posts/articles/get_started).
|
||||
- Access a version of Spiff hosted on the internet.
|
||||
|
||||
Setting up the SpiffWorkflow backend project locally can be straightforward once you're aware of the dependencies and options available. Whether you choose to clone the `sample-process-models` repository, use a different git repository, or opt for Docker Compose, the solutions provided should help you get started without any hitches.
|
||||
|
||||
|
||||
Setting up the SpiffWorkflow backend project locally can be straightforward once you're aware of the dependencies and options available. Whether you choose to clone the `sample-process-models` repository, use a different git repository, or opt for Docker Compose, the solutions provided should help you get started without any hitches.
|
||||
|
||||
If you encounter further issues, always refer back to the repository's README or seek assistance from our discord community.
|
||||
If you encounter further issues, always refer back to the repository's README or seek assistance from our discord community.
|
||||
|
|
|
|||
|
|
@ -25,12 +25,13 @@ from spiffworkflow_backend.routes.user_blueprint import user_blueprint
|
|||
from spiffworkflow_backend.services.monitoring_service import configure_sentry
|
||||
from spiffworkflow_backend.services.monitoring_service import setup_prometheus_metrics
|
||||
|
||||
# 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.
|
||||
# This is necessary if you want to use use the pymysql library with sqlalchemy rather than mysqlclient.
|
||||
# This is only potentially needed if you want to run non-docker local dev.
|
||||
# See the repo's top-level README and the linked troubleshooting guide for details.
|
||||
# import pymysql;
|
||||
# pymysql.install_as_MySQLdb()
|
||||
|
||||
|
||||
class MyJSONEncoder(DefaultJSONProvider):
|
||||
def default(self, obj: Any) -> Any:
|
||||
if hasattr(obj, "serialized"):
|
||||
|
|
|
|||
Loading…
Reference in New Issue