{"id":19881413,"url":"https://github.com/giscience/heigit-disaster-portal","last_synced_at":"2026-05-30T23:31:32.093Z","repository":{"id":41316857,"uuid":"463158187","full_name":"GIScience/heigit-disaster-portal","owner":"GIScience","description":null,"archived":false,"fork":false,"pushed_at":"2023-09-21T12:46:09.000Z","size":23017,"stargazers_count":2,"open_issues_count":16,"forks_count":1,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-03-01T02:46:45.339Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GIScience.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-02-24T13:27:36.000Z","updated_at":"2022-12-12T09:50:49.000Z","dependencies_parsed_at":"2023-01-22T10:30:50.849Z","dependency_job_id":null,"html_url":"https://github.com/GIScience/heigit-disaster-portal","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/GIScience/heigit-disaster-portal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fheigit-disaster-portal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fheigit-disaster-portal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fheigit-disaster-portal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fheigit-disaster-portal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GIScience","download_url":"https://codeload.github.com/GIScience/heigit-disaster-portal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fheigit-disaster-portal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33714033,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T17:14:10.619Z","updated_at":"2026-05-30T23:31:32.076Z","avatar_url":"https://github.com/GIScience.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HeiGIT Disaster Portal API\n\n\u003e Copyright Notice: This repository is licensed under the GNU AGPLv3 license. The basic structure is generated using\n\u003e the [FastAPI project generator](https://github.com/tiangolo/full-stack-fastapi-postgresql) (MIT license).\n\u003e If you want to do a similar project, you might want to start there.\n\nThe HeiGIT disaster portal API was developed to allow the accessing, adding, deleting and editing of features that\ncan be used in requests to HeiGIT services in the form of a portal system between applications or users and\nservices provided by HeiGIT.\nThis portal should act as a single entry place to the various services ([openrouteservice], [ohsome] etc.) as well as\nallowing additional processing to be performed on either the requests made to these services, or the responses\nreturned from them.\n\n[openrouteservice]: https://openrouteservice.org \"ORS website\"\n[ohsome]: https://ohsome.org \"ohsome website\"\n\nIn the initial version, the portal will only communicate with [openrouteservice], and will be used for adding avoid\nareas to requests which will be provided by an external source.\n\nTo accomplish this, there will need to be two APIs - one for maintaining the database of features, and one for making\nrequests against the HeiGIT services.\n\nThe API for communicating with services should be kept as close to the original requests as possible with minimal\nalterations and additional parameters.\n\nThe avoid-areas functionality should be able to identify features from the database that would be avoid-areas for the\nrequest without the user having to explicitly pass these areas in with their request.\nIt should also be able to strip these derived areas from the meta information in the response, where normally the full\nquery passed to openrouteservice is added.\nIn the case of the portal, the request to [openrouteservice] will contain information not directly specified by the user,\nand it may be desired (e.g. to reduce network transmission) to remove this information from the response.\n\nRequirements:\n- docker\n- docker-compose (included in mac and windows docker installations)\n\n\n## Production setup\n\n```sh\n# copy .env-sample to .env and adjust settings\ncp .env-sample .env\n\n# builds the docker disaster-area-portal image and dap-api container\ndocker-compose build\n\n# deploy dap-api and dap-db in background\ndocker-compose up -d\n\n# check api logs\ndocker logs -f dap-api\ndocker logs --tail 200 dap-api\n\n# grep docker logs using `2\u003e\u00261`\ndocker logs dap-api 2\u003e\u00261 | grep WARNING\n```\n\nThe interactive api documentation can be accessed at http://localhost:8080/api/v1/docs\nor alternative documentation on http://localhost:8080/api/v1/redoc\n\n## Development setup\n\nRequirements:\n- docker\n- docker-compose (included in mac and windows docker installations)\n- python3.10+\n\n```\n# Install poetry\ncurl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py | python -\n\n# enable poetry command (check [poetry documentation](https://python-poetry.org/docs/#enable-tab-completion-for-bash-fish-or-zsh) for shell completion setup)\nsource $HOME/.poetry/env\n```\n\nOn some systems where python2 and python3 are installed in parallel (e.g. Ubuntu), above installation method for poetry \nmay lead to problems due to poetry trying to use python 2. In case you see such an error message, try installing poetry \nvia pip:\n```\n# Install poetry\npip3 install poetry\n```\n\nNow we can install all dependencies locally.\n```\n# install dependencies\npoetry install --no-root\n```\n\nWhen using [PyCharm](https://www.jetbrains.com/pycharm/) you can use the [Poetry plugin](https://plugins.jetbrains.com/plugin/14307-poetry) \nto create an  interpreter with a python3.10 base or higher. It should use the virtual environment poetry has created. \nAfter creating it, you might need to close and open PyCharm again, so the Project uses now the correct interpreter and \nenv. In case pycharm creates a separate virtual env, you could prevent poetry from creating further virtual envs by \nrunning:\n```\npoetry config virtualenvs.create false\n```\n\nCopy `.env-sample` to `.env` and adjust settings\n```\ncp .env-sample .env\n```\n\nBuild the development image\n```\ndocker-compose -f docker-compose.reload.yml build\n```\n\nThis will build an image for 3 containers:\n- dap-api-reload: fast api app with reload on file change (localhost:8081)\n- dap-db: default postgis database also used with docker-compose.yml\n- dap-test-db: separate test database to not clutter production db\n\nAdditionally, you can create a _docker-compose run configuration_ with PyCharm.\nThe advantage of this:\n- only a few clicks to start\n- automatically connects and opens the Services Toolbar (inspect docker stuff: images, containers, logs, bindings etc.)\n\n1. Click the dropdown left of the Run Button (Play symbol) and click edit configurations\n1. Click `+`(add new configuration) and choose Docker Compose\n1. Set the name e.g. Reload\n1. Compose file(s): `./docker-compose.reload.yml;`\n1. Service(s): `dap-api-reload, dap-db, dap-test-db`\n1. Click OK\n\nCreate and run development containers (or run the configuration)\n```\ndocker-compose -f docker-compose.reload.yml up -d\n```\n\n_Note: The first time it will take some time until the db containers are configured. The dap-api-reload container won't\nbe able to connect right away._ \n\nYou can test the service through the interactive docs on http://localhost:8081/docs\n\n### Debugging\n\nTo be able to add breakpoints you need to add a _python run configuration_ for the [debug.py script](./dap_api/app/debug.py):\n1. Click the dropdown left of the Run Button (Play symbol) and click edit configurations\n1. Click `+`(add new configuration) and choose Python\n1. Set the name e.g. Debug\n1. Choose the file: `\u003cproject root\u003e/dap_api/app/debug.py`\n1. Interpreter should be the Project interpreter\n1. The working directory should be `\u003cproject root\u003e/dap_api/app`\n1. Switch to the **EnvFile** tab (requires [EnvFile plugin](https://plugins.jetbrains.com/plugin/7861-envfile))\n1. Click **Enable EnvFile**\n1. Click the \"+\" to add both `.env` \u0026 `.env-dev` files located in the project root (in this order !). If the `.env` \u0026 `.env-dev` files do not show up, enable showing hidden files. (Mac: Command+Shift+Dot)   \n1. Click OK\n\n\nClick the debug button on the previously created run configuration.\n\nTo test if the breakpoints are working, add one in the return line of the root path function (`@app.get(\"/\")` decorator)\nand open http://localhost:8083 in your browser.\n\n\n### Testing\n\n**Make sure the `dap-test-db` container is running**\n(If you always forget to do so, you can create a python run config for the `prestart_test_db.py` and let it run before the tests.)\n\nTo quickly run tests you can create a _pytest run configuration_:\n\n1. Click the dropdown left of the Run Button (Play symbol) and click edit configurations\n1. Click `+`(add new configuration) and choose pytest\n1. Set the name e.g. Test\n1. Interpreter should be the poetry one by default\n1. Working directory: `\u003cproject_root\u003e/dap_api/app/app/test`\n1. Switch to the **EnvFile** tab (requires [EnvFile plugin](https://plugins.jetbrains.com/plugin/7861-envfile))\n1. Click **Enable EnvFile**\n1. Click the \"+\" to add both `.env` \u0026 `.env-dev` files located in the project root (in this order !)\n1. Click OK\n1. In the project browser, right-click on the folder `\u003cproject_root\u003e/dap_api/app` and select Mark Directory as -\u003e\nSources Root. (**NOT the `db_api/app/app` folder**)\n\nWill open a user-friendly test interface, instead of scrolling through console :+1:\n(Also having the option to only rerun failed tests)\n\nYou will also be able to debug the tests if you run this config in _debug mode_.\n\nAlternatively you could run the tests within the `dap-api-reload` docker container:\n```\n# access the reload container\ndocker exec -i -t dap-api-reload bash\n\n# run the tests (you should be in /app already)\npytest\n```\n\n### Coverage\nFor displaying test coverage during development there are 2 viable options:\n\n1. Use the _Run pytest with coverage_ button (next to the debug button) for the previous pytest configuration.\nThis is a bit slower and creates coverage for the whole project.\nAlso, it is only available in the professional PyCharm Edition.\nIt will visually highlight all parts in the code that are not covered by tests yet.\n \n1. Add `--cov=app --cov-report=term-missing` as _Additional Arguments_ to the pytest configuration.\nWith this the pytest output will also create a coverage report including the lines \"missed\", blocks that were not\nexecuted with the test.\n**important:** PyCharm somehow uses the same helpers for coverage \u0026 debugging, so when using this approach,\nyour breakpoints will not be hit. You can either add the coverage as a second pytest config, or add `--no-cov` as\n_Additional Arguments_ to the pytest configuration, and switch back and forth between debug and coverage mode by\nadding and removing `--no-cov` from the config.\n\n\u003e For the second option you need to check `Pytest: don't add \"--no-header --no-summary -q\"` in `Preferences` \u003e\n\u003e `Advanced Settings` in PyCharm\n\nOf course, you can also run pytest with coverage in the reload-container with\n`pytest --cov=app --cov-report=term-missing`.\n\n---\n\nA html coverage report can be created to access coverage on an interactive website.\n```\n# run the tests with coverage (or add `--cov-report=html` to _Additional Arguments_)\npytest --cov=app --cov-report=html\n```\nOpen the created `dap-api/app/app/tests/htmlcov/index.html` in any browser.\n\nIf this is working correctly the code coverage can be displayed e.g. with codecov as a badge on the repository.\n\n### Database migrations\n\nAs during local development your app directory is mounted as a volume inside the container,\nyou can also run the migrations with `alembic` commands inside the container, and the migration\ncode will be in your app directory (instead of being only inside the container).\nSo you can add it to your git repository.\n\nMake sure you create a \"revision\" of your models and that you \"upgrade\" your database with that revision every time you \nchange them.\nThis is what will update the tables in your database.\nOtherwise, your application will have errors.\n\n* Start an interactive session in the backend container:\n\n```console\n$ docker exec -it dap-api-reload bash\n```\n\n* If you created a new model in `./app/app/models/`, make sure to import it in `./app/app/db/import_models.py`,\nthat imports all the models that will be used by Alembic.\n\n* After changing a model (for example, adding a column) inside the container, create a revision, e.g.:\n\n```console\n$ alembic revision --autogenerate -m \"Add column last_name to User model\"\n```\n\n* Commit to the git repository the files generated in the alembic directory.\n\n* After creating the revision, run the migration in the database (this is what will actually change the database):\n\n```console\n$ alembic upgrade head\n```\n\nIf you don't want to start with the default models and want to remove them / modify them, from the beginning,\nwithout having any previous revision, you can remove the revision files (`.py` Python files) under `./backend/app/alembic/versions/`.\nThen create a first migration as described above.\n\nSee Readme in alembic for further information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiscience%2Fheigit-disaster-portal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgiscience%2Fheigit-disaster-portal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiscience%2Fheigit-disaster-portal/lists"}