Tech 2492: Fix conservation builder typo and add to README's (#330) (#…

…331) * Add support for basic Auth * test commit * fix jitter on cb directions window scroll * update readmes * make CB header reszing based on availalbe space and not on scrolling * revert admin-role super admin config changes * attmepting to revert changes to config-sync --------- Co-authored-by: Simao Rodrigues <[email protected]> Co-authored-by: Andrés González <[email protected]> Co-authored-by: Simão Rodrigues <[email protected]> Co-authored-by: Clément Prod'homme <[email protected]> Co-authored-by: Will <[email protected]>
SkyTruth · Feb 3, 2025 · 1f3769f · 1f3769f
1 parent e9fda10
commit 1f3769f
Show file tree

Hide file tree

Showing 6 changed files with 612 additions and 521 deletions.
diff --git a/README.md b/README.md
@@ -16,17 +16,39 @@ External services:
 
 - *Mapbox*: used for serving layers for the map
 
-- *HubSpot*: used for the contact form, see [configuration instructions](hubspot.md)
+- *HubSpot*: used for the contact form, see [configuration instructions][hubspot]
 
 This repository contains all the code and documentation necessary to set up and deploy the project. It is organised in 5 main subdirectories, with accompanying documentation inside each.
 
-| Subdirectory name | Description                                                 | Documentation                                                                                            |
-|-------------------|-------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|
-| frontend          | The Next.js client application                            | [frontend/README.md](frontend/README.md)             |
-| cms               | The Strapi CMS / API                            | [cms/README.md](cms/README.md)             |
-| cloud_functions/analysis   | The on-the-fly analysis cloud function   | [cloud_functions/analysis/README.md](cloud_functions/analysis/README.md)               |
-| data           | The Python data importers and uploaders   | [data/README.md](data/README.md)               |
-| infrastructure    | The Terraform project & GH Actions workflow (provisioning & deployment to Google Cloud Platform) | [infrastructure/README.md](infrastructure/README.md) |
+| Subdirectory name        | Description                                                                                      | Documentation                               |
+|--------------------------|--------------------------------------------------------------------------------------------------|---------------------------------------------|
+| frontend                 | The Next.js client application                                                                   | [frontend][frontend]                        |
+| cms                      | The Strapi CMS / API                                                                             | [cms]                                       |
+| cloud_functions/analysis | The on-the-fly analysis cloud function                                                           | [cloud functions][cloud_functions_analysis] |
+| data                     | The Python data importers and uploaders                                                          | [data]                                      |
+| infrastructure           | The Terraform project & GH Actions workflow (provisioning & deployment to Google Cloud Platform) | [infrastructure]                            |
+
 
 ### Deployment and Infrastructure
 The project is deployed on the Google Cloud Platform (GCP) using GitHub Actions for continuous integration and deployment. The infrastructure is provisioned and managed using Terraform scripts, ensuring consistent and reproducible deployments.
+
+### Development
+In General each of subdirectories listed above act as standalone services and can be developed in isolation. For detailed instructions on development in those services please see the linked README's for the given service. There are, however, a few exceptions to this which are outlined below.
+
+#### Frontend Typescript Types
+Type definitions and internal data fetching hooks are automatically generated via integrations with [Orval][orval] and [Strapi][strapi]. Please see the [frontend documentation][frontend_types] for how to manage this dependency when developing locally.
+
+#### Development Hooks
+This repo uses `husky` to manage development flow hooks. There are hooks for: `pre-commit`, `post-checkout`, and `post-merge`. These hooks ensure the code is linted and formatted, as well as ensuring that generated types are up to date and the Strapi CMS config models are all up to date. For these checks to pass you must have an accurate `.env` file in the CMS directory and have the config file synced from the Strapi back office. Please refer to the [developing strapi docs][strapi_config] and the [strapi config sync docs][strapi_config_sync] to set this up prior to branching and committing. 
+
+[cloud_functions_analysis]: cloud_functions/analysis/README.md
+[cms]: cms/README.md
+[data]: data/README.md
+[frontend]: frontend/README.md
+[frontend_types]: frontend/README.md#automatic-type-building
+[hubspot]: hubspot.md
+[infrastructure]: infrastructure/README.md
+[orval]: https://orval.dev/overview
+[strapi]: https://strapi.io/
+[strapi_config_sync]: cms/README.md#config-sync-plugin-and-configuration-version-control
+[strapi_config]: cms/README.md#local-config-setup
diff --git a/cms/README.md b/cms/README.md
@@ -1,18 +1,33 @@
 # CMS / API
 
-This directory contains a [Strapi](https://strapi.io/) headless CMS, which provides a backoffice and an API for .
+This directory contains a [Strapi][strapi] headless CMS, which provides a backoffice and an API for the PostrgreSQL database backing the 30x30 tracker.
 
-Strapi comes with a full featured [Command Line Interface](https://docs.strapi.io/developer-docs/latest/developer-resources/cli/CLI.html) (CLI) which lets you scaffold and manage your project in seconds.
+Strapi comes with a full featured [Command Line Interface][strapi_cli] (CLI) which lets you scaffold and manage your project in seconds.
 
 ## Config
 
-The CMS needs to be configured with server and PostgreSQL database instance connection details. Please check the `.env.example` file for required environment variables. Those are set by Terraform in GH Secrets, and then passed into the docker images during deployment by GH Actions. Please refer to [infrastructure documentation](../infrastructure/README.md) for details.
+The CMS needs to be configured with server and PostgreSQL database instance connection details. Please check the `.env.example` file for required environment variables. Those are set by Terraform in GH Secrets, and then passed into the docker images during deployment by GH Actions. Please refer to [infrastructure documentation][infrastructure] for details.
+
+### Local Config Setup
+In order to make changes to the database schema or to add new data to exiting tables, you need to make the desired changes in the [strapi backoffice][backoffice]. The following steps are also needed for initial development to ensure database configs are in sync with prod, even if no changes are being made to the database. To set this up:
+- Create a new Postgres DB on your local machine
+- Start your local postgres server
+- Install the postgis extension on your new table
+- Update the `.env` file to contain the credentials for the local database
+- [Build] and [Start the local server][start]
+  - This will perform the necessary migrations to make your local database schema match the production DB schema. It does not, however, populate the DB with any data
+- Navigate to the [local backoffice][local_backoffice]
+- create your personal credentials to log in with
+  - There is no local password recovery. If you need to reset local auth, you'll need to start fresh with a new local database
+- From the left nav drawer navigate `Settings -> Config Sync -> Interface`
+- If there are difference between the DB and the [sync directory][sync] they will be highlighted here. Select Import to sync your DB with the [sync directory][sync]
+  - This will synchronize your local DB configs with the production configs
 
 ## Run locally
 
 ### `develop`
 
-Start your Strapi application with autoReload enabled. [Learn more](https://docs.strapi.io/developer-docs/latest/developer-resources/cli/CLI.html#strapi-develop)
+Start your Strapi application with autoReload enabled. [Learn more][strapi_cli_develop]
 
 ```
 npm run dev
@@ -22,7 +37,7 @@ yarn dev
 
 ### `start`
 
-Start your Strapi application with autoReload disabled. [Learn more](https://docs.strapi.io/developer-docs/latest/developer-resources/cli/CLI.html#strapi-start)
+Start your Strapi application with autoReload disabled. [Learn more][strapi_cli_develop]
 
 ```
 npm run start
@@ -32,7 +47,7 @@ yarn start
 
 ### `build`
 
-Build your admin panel. [Learn more](https://docs.strapi.io/developer-docs/latest/developer-resources/cli/CLI.html#strapi-build)
+Build your admin panel. [Learn more][strapi_cli_build]
 
 ```
 npm run build
@@ -49,7 +64,7 @@ Open the app at http://localhost:1337
 
 ## Deploy
 
-Deployment to GCP handled by GH Actions. Please refer to [infrastructure documentation](../infrastructure/README.md).
+Deployment to GCP handled by GH Actions. Please refer to [infrastructure documentation][infrastructure].
 
 ## API documentation
 
@@ -94,9 +109,13 @@ Tooltips and dictionary values for the dashboard:
 - mpaa-protection-level
 - protection-status
 
+### Updating models via the backoffce
+
+Changes to the database need to be made via the Strapi backoffice locally. To do this, follow the [local config setup instructions][local-config-setup]. Then make your changes in the [local backoffice][local_backoffice]. This will update the corresponding files in the this directory. Merging these changes to the `develop` brach migrate the changes to the staging database and similarly for merges to `main` and the production database
+
 ### Models updated by scripts
 
-These models are updated by an import script, which utilises the Strapi import / export API. Please refer to [data documentation](../data/README.md).
+These models are updated by an import script, which utilises the Strapi import / export API. Please refer to [data documentation][data].
 
 - fishing-protection-level-stat
 - habitat-stat
@@ -108,14 +127,31 @@ These models are updated by an import script, which utilises the Strapi import /
 ## config-sync plugin and configuration version control
 This Strapi is configured to use the [config-sync plugin](https://market.strapi.io/plugins/strapi-plugin-config-sync), which allows to version control config data and migrate it between environments.
 
-Examples of configuration under config-sync are user and admin role permissions, API permissions and settings of the admin panel. The consequence of this is that if any settings are changed directly in the staging / production admin panel, but not synced in the repository, they will be overwitten on subsequent deployments.
+Examples of configuration under config-sync are user and admin role permissions, API permissions and settings of the admin panel. The consequence of this is that if any settings are changed directly in the staging / production admin panel, but not synced in the repository, they will be overwritten on subsequent deployments.
 
 ## Strapi resources
 
-- [Resource center](https://strapi.io/resource-center) - Strapi resource center.
-- [Strapi documentation](https://docs.strapi.io) - Official Strapi documentation.
-- [Strapi tutorials](https://strapi.io/tutorials) - List of tutorials made by the core team and the community.
-- [Strapi blog](https://docs.strapi.io) - Official Strapi blog containing articles made by the Strapi team and the community.
-- [Changelog](https://strapi.io/changelog) - Find out about the Strapi product updates, new features and general improvements.
+- [Resource center][strapi_rc] - Strapi resource center.
+- [Strapi documentation][strapi_docs] - Official Strapi documentation.
+- [Strapi tutorials][strapi_tutorials] - List of tutorials made by the core team and the community.
+- [Strapi blog][strapi_docs] - Official Strapi blog containing articles made by the Strapi team and the community.
+- [Changelog][strapi_changelog] - Find out about the Strapi product updates, new features and general improvements.
 
 Feel free to check out the [Strapi GitHub repository](https://github.com/strapi/strapi). Your feedback and contributions are welcome!
+
+[backoffice]: #updating-models-via-the-backoffce
+[build]: #build
+[data]: ../data/README.md
+[infrastructure]: ../infrastructure/README.md
+[local_backoffice]: http://localhost:1337/admin/
+[local_config_setup]: #local-config-setup
+[start]: #start
+[strapi]:https://strapi.io/
+[strapi_changelog]: https://strapi.io/changelog
+[strapi_cli]: https://docs.strapi.io/developer-docs/latest/developer-resources/cli/CLI.html
+[strapi_cli_build]: https://docs.strapi.io/developer-docs/latest/developer-resources/cli/CLI.html#strapi-build
+[strapi_cli_develop]: https://docs.strapi.io/developer-docs/latest/developer-resources/cli/CLI.html#strapi-develop
+[strapi_docs]: https://docs.strapi.io
+[strapi_rc]: https://strapi.io/resource-center
+[strapi_tutorials]: https://strapi.io/tutorials
+[sync]: ./config/sync/