Guide to the Toolbox Templating repo

Big picture, GitHub Branching

1. Try out new changes in a feature branch off of dev. Check that github actions (create_html.yml, validate_json_config.yml, and validate_json_model_list.yml) all pass.
2. Merge changes into dev (prefer using a pull request and using a rebase workflow). Once merged in, use a github action, dev_create_website_and_deploy.yml, to build the html pages and deploy them to 3.
3. The noaa-fit-dev repo's gh-pages branch is hosted on github pages. Navigate to https://nmfs-ost.github.io/noaa-fit-dev/ to preview the FIT website.
4. Once confirming the dev pages look good, merge changes into 4 (prefer a rebase workflow, or if appropriate, squash and merge workflow). Once merged in, use a github action (done automatically) to build the html pages and deploy them to 5. Delete the dev branch and recreate it from main (so that they are back in sync with the exact same commits). Any merged feature branches can also be deleted.
5. This is the production version of the NOAA fisheries site, advertised to the public. The noaa-fit repo's gh-pages branch is hosted on GitHub pages. Navigate to https://nmfs-ost.github.io/noaa-fit/ to see the production FIT site.

Webpage addresses on production

• FIT landing page (https://nmfs-ost.github.io/noaa-fit/)
• individual tool landing pages, toolbox hosted (e.g., https://nmfs-ost.github.io/noaa-fit/ASAP)

redirect pages

The following repos contain files that automatically redirect the old website locations:

• https://github.com/nmfs-fish-tools/nmfs-fish-tools.github.io
• https://github.com/noaa-fisheries-integrated-toolbox/noaa-fisheries-integrated-toolbox.github.io

Org Templating

This repository includes templates and JSON data for the FIT. python's jinja 2 is used to generate webpages from the html templates and JSON files (For R users, this approach is similar to using glue).

How to update or add tool landing pages

1. Changes should be made in a branch off of dev. In model_list_dir subfolder add or update .json files. Examples of json are available in the readme. If onboarding a new tool, the issue from the onboard-and-update repo should have a json based on user input that can be copy/pasted in, then checked. If the json is missing, it likely means the GitHub Action failed. Instead, the R code can be run locally, hard coding in the issue number.
2. If it is a new tool, add the name of the json file (minus the extension, case sensitive) to the list_of_models item in the models_all.json file.
3. Changes can be checked locally using instructions in the "Creating Webpages Locally From Templates" section of the readme.
4. After committing and pushing to dev, changes can be checked on the fit-dev site (may take a few minutes after pushing to dev to build and deploy). You can check that the fit-dev website has updated by looking at the dev repository. If GitHub actions on the dev branch are failing, look at them and make changes to code.
5. Once actions passing, share changed dev tool landing page with the person submitting the onboarding request (e.g., if the tool is called, my-tool, the dev tool landing page would be https://nmfs-ost.github.io/noaa-fit-dev/my-tool). Allow them to request changes or approve the landing page.
6. If the author approves, open an PR to main, which KD will look at and merge in if passing checks.

Explanation of JSON metadata

JSON data can be validated using schema.

See descriptions in the schema_model_list.json file.

Creating Webpages Locally From Templates

Python and its libraries Jinja2 and requests need to be installed locally.

pip install jinja2
pip install requests

From bash, run:

python create_tool_landing_page.py dev_config.json
python create_catalog_landing_page.py dev_config.json # or prod_config.json if building the production site.
python create_site_index_page.py dev_config.json # or prod_config.json if building the production site.

These are just the commands in create_html.yml. Note that this will create new webpages that should NOT be saved to the repository.

To view the webpages from VS code, try using the Live Preview Extension. You may need to add .html to the end of a link in order to view it properly. Sometimes the embedded preview doesn't work, so a separate browser window will need to be opened instead.

Overview of GitHub Actions in toolbox_web_templating

GitHub actions code (YAML files) live in the .github/workflows directory.

• create_html.yml: creates the html pages for viewing and saves them as artifacts. The files can be downloaded and examined. Runs on every push to any branch and manually.
• dev_create_website_and_deploy.yml: updates FIT dev site by deploying rendered html from the toolbox_web_templating dev branch to https://github.com/nmfs-ost/noaa-fit-dev/tree/gh-pages (gh-pages branch). Runs on every push to the dev branch and manually.
• prod_create_website_and_deploy.yml: updates FIT prod site by deploying rendered html from the toolbox_web_templating main branch to https://github.com/nmfs-ost/noaa-fit/tree/gh-pages (gh-pages branch). runs on every push to main and manually.
• validate_json_config.yml: check that prod_config.json,dev_config.json matches the JSON schema defined in schema_config.json and that models_all.json matches the JSON schema definied in schema_models_all.json. If the GitHub action fails, it will provide info on how the json files need to be modified to match the schema. Runs on every push to any branch, and manually.
• validate_json_model_list.yml: checks that the JSON files in model_list_dir matches the JSON schema defined in schema_model_list.json. If the GitHub action fails, it will provide info on how the json files need to be modified to match the schema. Runs on every push to any branch where there are changes to the files in model_list_dir and manually.

Personal Access Tokens and Secrets needed to deploy

For the GitHub Actions to deploy to the dev and production repositories, A fine-grained personal access token with write permissions on the repositories is needed. For nmfs-ost, Tokens can have a max. lifespan of 90 days.

1. Create a fine-grained personal access token. This token will need to have access to the nmfs-ost organization and access to the nmfs-ost/noaa-fit-dev, nmfs-ost/noaa-fit, and nmfs-ost/FIT_web_templating repositories. No organization permissions are needed, but it will need "read access to metadata" and "read and write access to code and deployments" for "repository permissions". Be sure to save the token string, as you will only be able to see it once! Treat it as you would a password, do not share it.
2. This token will need to be added as a secret. An admin can edit the existing secret called "FIT_DEPLOY_TOKEN" (visible to admins at https://github.com/organizations/nmfs-ost/settings/secrets/actions/FIT_DEPLOY_TOKEN) and add new value (being sure to save changes). Request help from a nmfs-ost admin by opening an issue in the nmfs-ost/admin repo, though DO NOT SHARE your token string in the issue!

Disclaimer

“The United States Department of Commerce (DOC) GitHub project code is provided on an ‘as is’ basis and the user assumes responsibility for its use. DOC has relinquished control of the information and no longer has responsibility to protect the integrity, confidentiality, or availability of the information. Any claims against the Department of Commerce stemming from the use of its GitHub project will be governed by all applicable Federal law. Any reference to specific commercial products, processes, or services by service mark, trademark, manufacturer, or otherwise, does not constitute or imply their endorsement, recommendation or favoring by the Department of Commerce. The Department of Commerce seal and logo, or the seal and logo of a DOC bureau, shall not be used in any manner to imply endorsement of any commercial product or activity by DOC or the United States Government.”