{"id":13949105,"url":"https://github.com/bcgov/gwells","last_synced_at":"2025-10-12T13:26:18.890Z","repository":{"id":37664910,"uuid":"83460090","full_name":"bcgov/gwells","owner":"bcgov","description":"Groundwater Wells and Aquifers application for the Ministry of Environment","archived":false,"fork":false,"pushed_at":"2025-07-09T16:44:09.000Z","size":131028,"stargazers_count":32,"open_issues_count":102,"forks_count":36,"subscribers_count":12,"default_branch":"release","last_synced_at":"2025-10-08T09:38:27.918Z","etag":null,"topics":["bcgov-csnr","dds","django","env","groundwater-data","vuejs"],"latest_commit_sha":null,"homepage":"https://apps.nrs.gov.bc.ca/gwells/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bcgov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/codeowners","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-02-28T17:22:23.000Z","updated_at":"2025-09-19T16:22:40.000Z","dependencies_parsed_at":"2024-03-25T10:07:58.166Z","dependency_job_id":"cf882183-4192-49ef-9d5b-3af702d725f4","html_url":"https://github.com/bcgov/gwells","commit_stats":{"total_commits":6755,"total_committers":73,"mean_commits":92.53424657534246,"dds":0.7502590673575129,"last_synced_commit":"8a4142dde72ec6bc8facdef0bc3b4f2bc972509c"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/bcgov/gwells","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcgov%2Fgwells","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcgov%2Fgwells/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcgov%2Fgwells/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcgov%2Fgwells/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bcgov","download_url":"https://codeload.github.com/bcgov/gwells/tar.gz/refs/heads/release","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcgov%2Fgwells/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005910,"owners_count":26083994,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"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":["bcgov-csnr","dds","django","env","groundwater-data","vuejs"],"created_at":"2024-08-08T05:01:38.430Z","updated_at":"2025-10-12T13:26:18.853Z","avatar_url":"https://github.com/bcgov.png","language":"Python","readme":"[![img](https://img.shields.io/badge/Lifecycle-Stable-97ca00)](https://github.com/bcgov/repomountie/blob/master/doc/lifecycle-badges.md)\n\n# Groundwater Wells and Aquifers (GWELLS)\n\nhttps://apps.nrs.gov.bc.ca/gwells/\n\n## Introduction\n\nThe Ministry of Environment receives and processes groundwater data and information related to the construction, alteration and decommissioning of groundwater wells. Well construction and reporting requirements are regulated under the Water Sustainability Act and Groundwater Protection Regulation. The information collected and stored is used by government and other users to help inform decisions related to the management of the groundwater resource in B.C.\n\nGWELLS, the new groundwater data repository, aims to improve the user experience when submitting and searching for well information, to improve the quality of the data being submitted, and to improve the overall functionality of the system to meet user and regulatory requirements.\n\nThe application is being developed as an open source solution.\n## Table of Contents\n\n1. [Using the GWELLS API](#Using-the-gwells-api)\n1. [DataBC Export](#databc-export)\n1. [Developing GWELLS](#Developing-gwells)\n   - [Setup Prerequisites](#setup-prerequisites)\n   - [Running the GWELLS application locally](#Running-the-GWELLS-application-locally)\n   - [Authentication](#Authentication)\n   - [Running tests](#Running-tests)\n   - [Making pull requests](#Making-pull-requests)\n1. [Architecture](#Architecture)\n1. [Contributing](#contributing)\n   - [Code With Us](#code-with-us)\n1. [License](#license)\n\n## Using the GWELLS API\n\nGWELLS maintains a REST API where public data relating to wells is made available for other applications and services.\n\nOur Swagger documentation is available at https://apps.nrs.gov.bc.ca/gwells/api/. Some examples of GWELLS endpoints:\n\nWells:\n\n```sh\n# all wells (paginated)\ncurl https://apps.nrs.gov.bc.ca/gwells/api/v1/wells\n\n# all wells in an area bounded by sw_lat, sw_long, ne_lat, and ne_long\ncurl https://apps.nrs.gov.bc.ca/gwells/api/v1/wells?sw_lat=51.599253\u0026sw_long=-128.220340\u0026ne_lat=52.108192\u0026ne_long=-127.150547\n```\n\nAquifers:\n\n```sh\n# all aquifers\ncurl https://apps.nrs.gov.bc.ca/gwells/api/v1/aquifers\n```\n\nSee the [Swagger documentation](https://apps.nrs.gov.bc.ca/gwells/api/) for more examples.\n\n## DataBC Export\n\nGWELLS Api is used by DataBC to export model information and provide well information on the DataBC website.\n\nThe command located in app/backend/gwells/management/commands/export_databc.py is used to pull data from the gwells database and export it for consumption in DataBC.\n\nIf a new field(s) are needed for export, this export_databc.py has raw sql queries that need to be updated with the required fields. Descriptions are also needed for the swagger documentation that are pulled from the db_comment fields in the django models. Both the raw sql queries and the db_comment field on the model need to be updated for new fields.\n\n## Developing GWELLS\n\n### Setup Prerequisites\n\n**Software Requirements**\n\n- Docker Desktop\n- Node\n\n**Actions to take**:\n\n- [Connecting to Minio](#connecting-to-minio)\n- [CSSO Authentication](#authentication)\n- You will need to login to [artifactory](https://artifacts.developer.gov.bc.ca/ui/login/) with your IDIR so a member of Sustainment Team can add you.\n\n### Connecting to Minio\n\nFor gwells to interact with your local instance of Min.IO add the appropriate settings to your local machines `HOSTS` file:\n\n```\n127.0.0.1 minio-public\n127.0.0.1 minio-private\n```\n\n### Authentication\n\nSome GWELLS pages (submitting new well reports, adding or editing aquifers, or adding or editing qualified well drillers to the registry) require authentication. Authentication uses the Province's Single Sign-On system. A GWELLS team member can request access for collaborators if needed.\n\n### Running the GWELLS application locally\n\n- [Clone the GWELLS repository](https://help.github.com/en/articles/cloning-a-repository)\n- From the gwells folder run `docker-compose up -d`\n\nLogin to Artifactory for pulling the backend base image:\n\n```sh\ndocker login -u \u003csvc-usn\u003e -p \u003csvc-pwd\u003e artifacts.developer.gov.bc.ca/g26e-backend-docker-local\n```\n\nReplace svc-usn and svc-pwd with Artifactory service account credentials obtained from Openshift (under artifacts-default-tulivf secrets)\n\nThen, run the application with Docker:\n\n```sh\ncd gwells\ndocker-compose up\n```\n\n### Running GWELLS locally with a connection to Staging's Database\n\nTo have a more complete dataset while running locally, you can opt to point the backend at GWELLS' staging database **while using the BC Government VPN**. This will provide a more robust dataset for debugging or feature testing.\n\n1. Duplicate `.env.template` and rename the new file as `.env.test`\n\n2. Using the database secrets from GWELLS' staging namespace on OpenShift, replace the variables in your new `.env.test` file. You'll need to change `ENVIRONMENT` to 'test' as well to ensure the proper `command` is run from the `app/scripts/backend-command-script.sh` file.\n\n    Note: to get the `GWELLS_SERVICE_HOST` and `GWELLS_SERVICE_PORT`, use the `oc` CLI and login to GWELLS' test namespace; run the following command to view the `TransportServer` for the staging database:\n\n    ```\n    oc project 26e83e-test\n\n    oc -n 26e83e-test get ts\n    ```\n\n    This should print out a `VIRTUALSERVERADDRESS` (the `GWELLS_SERVICE_HOST`) and a `VIRTUALSERVERPORT` (the `GWELLS_SERVICE_PORT`)\n\n    ```\n    NAME              VIRTUALSERVERADDRESS   VIRTUALSERVERPORT   POOL          POOLPORT   IPAMLABEL   IPAMVSADDRESS   STATUS   AGE\n    yourservice-tsc   142.34.194.68          65555               yourservice   8000                   None            Ok       21d\n    ```\n\n    Your `.env.test` file should look something like this:\n\n    ```\n    # .env for test environment\n    ENVIRONMENT=test\n    API_TARGET=http://backend:8000/\n    DATABASE_USER=\u003cdb-user\u003e\n    DATABASE_PASSWORD=\u003cdb-password\u003e\n    GWELLS_SERVICE_HOST=142.34.194.68\n    GWELLS_SERVICE_PORT=\u003cport-number\u003e\n    ```\n\n3. Once `.env.test` has the proper environment variables, run the `docker-compose up` command with the `--env-file` flag:\n\n    ```\n    docker-compose --env-file ./.env.test up\n    ```\n\nYou should now have a local build with a backend that points to staging's database. **Be mindful when saving or changing data to the staging database**.\n\nIf you're encountering any issues with the build, ensure that your VPN is connected and working properly.\n\n\u003eMinio doesn't download while connected using the VPN. This is a known issue.\n\n### Running GWELLS in Debug Mode\n\nEnsure you have a `launch.json` file in the `.vscode` directory.\n\n```json\n{\n  \"version\": \"0.2.0\",\n  \"configurations\": [\n    {\n      \"name\": \"Remote Django App\",\n      \"type\": \"python\",\n      \"request\": \"attach\",\n      \"pathMappings\": [\n        {\n          \"localRoot\": \"${workspaceFolder}/app/backend\",\n          \"remoteRoot\": \"/app/backend\"\n        }\n      ],\n      \"port\": 3000,\n      \"host\": \"localhost\"\n    }\n  ]\n}\n```\n\nIn VS Code, press `F5` or go to **Run \u003e Start Debugging** to run in debug mode.\n\nYou can now add breakpoints within GWELLS - [more information about debugging in VS Code here.](https://code.visualstudio.com/docs/editor/debugging)\n\n### Connecting to PGAdmin\n\n\u003e Information in this section reflects docker-compose as of `Nov 8th, 2023`\n\nPG Admin is setup in the `docker-compose up` and requires no additional installations\n\nSteps:\n\n1. Connect to Pgadmin through [localhost](http://localhost:5050)\n1. Login using username: `admin@gwells.com`, password: `admin`\n1. Right click `Server` -\u003e `Register` -\u003e `Server`\n1. Enter any meaningful name in `Name`\n1. Under the `Connection` tab supply the following values\n\n| Field               | Value    |\n| ------------------- | -------- |\n| Host name / address | `db`     |\n| Port                | `5432`   |\n| Username            | `gwells` |\n| Password            | `test1`  |\n\nVisit the following links to browse the API and frontend applications:\n\n- Django REST API development server: http://localhost:8000/gwells/api/\n- Vue frontend development server: http://localhost:8080/\n\n### Running tests:\n\nFor comprehensive testing information visit the [Wiki](https://github.com/bcgov/gwells/wiki/Testing)\nPostman API tests:\nImport the json test collections in the `api-tests/` folder into [Postman](https://www.getpostman.com/).\n\n### Import a Shapefile\n\nSingle shapefile, with aquifer ID specified in CLI.\n\n```\ndocker-compose exec backend python manage.py import_shapefile 2 aquifers/fixtures/shp/shapefile.zip\n```\n\nBulk import, requires the AQ_NUMBER attribute on each polygon. Requires a folder with shapefiles to be prepared and passed in (zipped or not). Note: if DEBUG=True, all geometries will be uploaded to a random aquifer instead of the one matching its' number, so we can test locally with a development database.\n\n```\nmkdir app/backend/bulk\nmv DATABC_EXPORT_FILE.zip app/backend/bulk/\n\ndocker-compose exec backend python manage.py import_bulk_shapefile bulk\n```\n\n### Importing Licences\n\nTo download new licence data from DataBC and merge it into your DB, do\n\n```\ndocker-compose exec backend python manage.py import_licences\n```\n\n### Making pull requests\n\nPull requests made from branches in the bcgov/gwells repo will kick off a dev pipeline, which runs tests and deploys a preview environment containing your changes. The pull request page will update when the environment is deployed and mandatory checks (unit tests, etc.) pass or fail.\n\n## Architecture\n\nGWELLS uses PostgreSQL (with PostGIS), Django REST Framework, and Vue.js. We also use both AWS S3 and a self-hosted Minio service for storing documents.\n\nOur production and staging environments run on an OpenShift container platform cluster. OpenShift templates for services are located in the `openshift/` folder, along with more information about dev and staging environments on our cluster.\n\n![GWELLS container diagram](pics/container_diagram.png)\n\n## Contributing\n\nGovernment employees, the public and members of the private sector are encouraged to contribute. Please read and follow our [Code of Conduct](https://github.com/bcgov/gwells/blob/master/CODE_OF_CONDUCT.md).\n\nAll contributors retain original copyright, but are granting a world-wide, royalty-free, perpetual, irrevocable, non-exclusive, transferable license to all users. This project is covered by an [Apache v2.0 license](https://github.com/bcgov/gwells/blob/master/LICENSE).\n\n### Code With Us\n\nMany of our features have been developed by members of the community. Check the [BC Developer Exchange website](https://bcdevexchange.org/), where paid opportunities to build features for GWELLS and other applications are posted.\n\n## License\n\nCode released under the [Apache License, Version 2.0](https://github.com/bcgov/gwells/blob/master/LICENSE).\n\n## Additional Documentation\n\nMore documentation for the repository can be found in the following places\n\n- [Frontend](/app/frontend/README.md)\n- [OpenShift](/openshift/README.md)\n- [Tests](/tests/api-tests/README.md)\n\n## New pipeline deployment instructions\n\nDev Environment\n-\nSteps before merging Pull Request into 'release':\n  1. Login to OpenShift\n\n  2. Navigate to '26e83e-tools' in projects\n\n  ![alt text](pics/image.png)\n\n  3. Make sure you are in the administrator view\n\n  ![alt text](pics/image-1.png)\n\n  4. Go to Builds -\u003e BuildConfigs\n\n  ![alt text](pics/image-2.png)\n\n  5. Find 'gwells-frontend'\n\n  ![alt text](pics/image-3.png)\n\n  6. Click on the YAML tab\n\n  ![alt text](pics/image-4.png)\n\n  7. Find the 'VITE_AXIOS_BASE_URL' environment variable and change the url to include 'dev'. (It may currently already say dev, or test or prod)\n\n  ![alt text](pics/image-8.png)\n\n  8. Hit 'save'\n\n  ![alt text](pics/image-9.png)\n\n  9. You can now merge the Pull Request\n  \n  10. A build for the frontend and backend will now be triggered and automatically deploy to the dev environment once built.\n\n  Test Environment\n  -\n  Steps before merging Pull Request into 'release':\n  1. Login to OpenShift\n\n  2. Navigate to '26e83e-tools' in projects\n\n  ![alt text](pics/image.png)\n\n  3. Make sure you are in the administrator view\n\n  ![alt text](pics/image-1.png)\n\n  4. Go to Builds -\u003e BuildConfigs\n\n  ![alt text](pics/image-2.png)\n\n  5. Find 'gwells-frontend'\n\n  ![alt text](pics/image-3.png)\n\n  6. Click on the YAML tab\n\n  ![alt text](pics/image-4.png)\n\n  7. Find the 'VITE_AXIOS_BASE_URL' environment variable and change the url to include 'test'. (It may currently already say dev, or test or prod)\n\n  ![alt text](pics/image-10.png)\n\n  8. Hit 'save'\n\n  ![alt text](pics/image-9.png)\n\n  9. You can now merge the Pull Request\n\n  Steps after merging Pull Request into 'release':\n\n  1.  Once the frontend and backend builds are complete navigate to Pipelines -\u003e Pipelines\n\n  ![alt text](pics/image-11.png)\n\n  2. Then select 'promote-to-test'\n\n  ![alt text](pics/image-12.png)\n\n  3. Finally Select Actions -\u003e Start\n\n  ![alt text](pics/image-13.png)\n\n  4. The frontend and backend will then deploy to the test environment\n\nProd Environment\n  -\n  Steps before merging Pull Request into 'release':\n  1. Login to OpenShift\n\n  2. Navigate to '26e83e-tools' in projects\n\n  ![alt text](pics/image.png)\n\n  3. Make sure you are in the administrator view\n\n  ![alt text](pics/image-1.png)\n\n  4. Go to Builds -\u003e BuildConfigs\n\n  ![alt text](pics/image-2.png)\n\n  5. Find 'gwells-frontend'\n\n  ![alt text](pics/image-3.png)\n\n  6. Click on the YAML tab\n\n  ![alt text](pics/image-4.png)\n\n  7. Find the 'VITE_AXIOS_BASE_URL' environment variable and change the url to include 'prod'. (It may currently already say dev, or test or prod)\n\n  ![alt text](pics/image-14.png)\n\n  8. Hit 'save'\n\n  ![alt text](pics/image-9.png)\n\n  9. You can now merge the Pull Request\n\n  Steps after merging Pull Request into 'release':\n\n  1.  Once the frontend and backend builds are complete navigate to Pipelines -\u003e Pipelines\n\n  ![alt text](pics/image-11.png)\n\n  2. Then select 'promote-to-prod'\n\n  ![alt text](pics/image-15.png)\n\n  3. Finally Select Actions -\u003e Start\n\n  ![alt text](pics/image-13.png)\n\n  4. The frontend and backend will then deploy to the prod environment","funding_links":[],"categories":["Python","Natural Resources"],"sub_categories":["Water Supply and Quality"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbcgov%2Fgwells","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbcgov%2Fgwells","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbcgov%2Fgwells/lists"}