From deb76c20dd53cedd30fda3e7564ac3a60156b6a3 Mon Sep 17 00:00:00 2001 From: djnunez-aot <103138766+djnunez-aot@users.noreply.github.com> Date: Fri, 28 Jun 2024 12:10:38 -0400 Subject: [PATCH] Update Readme (#2324) * update readme * update read me --- epictrack-api/README.md | 133 ++++++++++++++++++++++++++++++++++------ 1 file changed, 113 insertions(+), 20 deletions(-) diff --git a/epictrack-api/README.md b/epictrack-api/README.md index a3d7e5d9b..49aa9ef38 100644 --- a/epictrack-api/README.md +++ b/epictrack-api/README.md @@ -1,37 +1,130 @@ [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](../LICENSE) [![Report API CI](https://github.com/bcgov/eao-project-reports/actions/workflows/reports-api-ci.yml/badge.svg)](https://github.com/bcgov/eao-project-reports/actions/workflows/reports-api-ci.yml) - # REPORTS API EAO Project report services. +# EpicTrack Local Setup + +## GitHub Repository + +[EPIC.track GitHub](https://github.com/bcgov/EPIC.track) + +- Fork a new branch and point to the `develop` branch. + +## Required Access + +Zenhub, Openshift, Keycloak + +- You will need access. For now, contact dinesh.pb@aot-technologies.com + +## Development Environment Setup + +### Windows + +#### Database + +- Set up a Postgres database locally: [Docker Postgres](https://hub.docker.com/_/postgres) +- If you don’t have Docker, install it from: [Docker Desktop Install](https://docs.docker.com/desktop/install/windows-install/) + +### API Setup + +1. Open a terminal and navigate to `epictrack-api` +2. Run `docker-compose up` +3. In a separate terminal, navigate to `reports-api` +4. Create a virtual environment: [Python venv Documentation](https://docs.python.org/3/library/venv.html) +5. Activate the virtual environment and install the Python packages: + ```sh + python -m pip install -r path/to/requirements/dev.txt + python -m pip install -r path/to/requirements/prod.txt + ``` +6. Switch your interpreter correctly. Refer to the image below: + ![Interpreter Switch](path/to/image) +7. Set up environment variables in your system: + + - `FLASK_APP` + - `FLASK_ENV` + + Example: + + ```sh + export FLASK_APP=manage.py + export FLASK_ENV=development + ``` + +8. Configure `PYTHONPATH` to your project's folder location up to `epictrack-api/src`. + +9. Create a `.env` file in your `epictrack-api` folder. Example content: -## Development Setup + ```env + # Environment-specific settings for python-dotenv -1. Open the project in VS Code to treat it as a project (or WSL projec). To prevent version clashes, set up a -virtual environment to install the Python packages used by this project. -2. Run `make setup` to set up the virtual environment and install libraries. -3. Next run `pip install .` to set up the environment for running tests. + # ===== epictrack-api ===== -You also need to set up the variables used for environment-specific settings: -1. Copy the [dotenv template file](./docs/dotenv_template) to somewhere above the source code and rename to `.env`. You will need to fill in missing values. + # Connection to dev database. + DATABASE_URL="postgresql://postgres@localhost:8432/postgres" + DATABASE_USERNAME="reports" + DATABASE_PASSWORD="qwHAW6p3GI8AvOsM" + DATABASE_NAME="reports-db" + DATABASE_HOST="localhost" + DATABASE_PORT="8432" -## Running the Database on localhost + # Connection to unit test database. + DATABASE_TEST_URL="postgresql://postgres:postgres@localhost:8432/postgres" + DATABASE_TEST_USERNAME=postgres + DATABASE_TEST_PASSWORD=postgres + DATABASE_TEST_HOST=localhost + DATABASE_TEST_PORT="8432" + DATABASE_TEST_NAME=postgres -To prepare your local database: -1. In the [root project folder](../docker/docker-compose.yml): `docker-compose up -d` -2. In your `venv` environment: -``` -export FLASK_APP=manage.py -flask db upgrade -``` + # Flask settings + PYTHONWARNINGS="once" + FLASK_APP=manage.py + FLASK_ENV="development" + FLASK_DEBUG=True + POD_TESTING=True + SQLALCHEMY_ECHO=False + DEBUG=True + # Keycloak settings + JWT_OIDC_ISSUER=https://dev.loginproxy.gov.bc.ca/auth/ + JWT_OIDC_WELL_KNOWN_CONFIG=https://dev.loginproxy.gov.bc.ca/auth/realms/eao-epic/.well-known/openid-configuration + JWT_OIDC_ALGORITHMS=RS256 + JWT_OIDC_AUDIENCE=epictrack-web + JWT_OIDC_CLIENT_SECRET= + JWT_OIDC_JWKS_CACHE_TIMEOUT=300 + JWT_OIDC_CACHING_ENABLED=True -## Running API + KEYCLOAK_BASE_URL=https://dev.loginproxy.gov.bc.ca + KEYCLOAK_REALM_NAME=eao-epic + KEYCLOAK_ADMIN_CLIENT=realm-management + KEYCLOAK_ADMIN_SECRET=GET_FROM_KEYCLOAK + CONNECT_TIMEOUT=60 + ``` -1. Start the flask server with `(python -m flask run -p 5000)` -2. View the [OpenAPI Docs](http://127.0.0.1:5000/api/v1). +10. Debug locally in VS Code + - Open the application at the root level + - Click on the highlighted symbol to find a play button for the Reports API to open the API in debug mode. + +### Web Setup + +1. Download Node.js: [Node.js Download](https://nodejs.org/en) +2. Navigate to `epictrack-web` +3. Run `npm install` +4. Create a `.env` file in the `epictrack-web` folder. Example content: + ```env + REACT_APP_API_URL=http://localhost:3200 + REACT_APP_KEYCLOAK_URL=https://dev.loginproxy.gov.bc.ca + REACT_APP_KEYCLOAK_CLIENT=epictrack-web + REACT_APP_KEYCLOAK_REALM=eao-epic + PORT=3002 + ``` +5. Navigate to `epictrack-web` +6. Run `npm start` +7. Login with IDIR + +The application will open up on the port specified in the `.env` file. ## Running Liniting @@ -41,4 +134,4 @@ flask db upgrade ## Running Unit Tests 1. Tests are run from the Status bar at the bottom of the workbench in VS Code or `pytest` command. -2. Next run `make coverage` to generate the coverage report, which appears in the *htmlcov* directory. +2. Next run `make coverage` to generate the coverage report, which appears in the _htmlcov_ directory.