Changelog: Changelog.md
Netlify hosted, Gatsby built, storyblok headless cms site for alumni.stanford.edu
Development
cp example.env .env
* Manually find and add the `VAULT_ROLE_ID` and `VAULT_ROLE_ID` to .env
* Or, you can retrieve the `VAULT_ROLE_ID` and `VAULT_ROLE_ID` by first running `netlify login` then `netlify link`, then use the `netlify env:get VAR_NAME` command. After that manually add them to .env
* After the `VAULT_ROLE_ID` and `VAULT_SECRET_ID` environment variables have been added to .env,
get the FontAwesome NPM token from the Netlify site settings in environment variables and install the packages
FONTAWESOME_NPM_AUTH_TOKEN=MYFATOKEN npm install
* Retrieve all other environment variables from the vault
npm run vault:local
* Then fire up your development server using gatsby
npm run dev
* Or a netlify development server
netlify dev
You will need an access token to connect to a storyblok space. You can contact a member on the project team to get one but if you follow the installation steps you should be able to get one from vault. Development
builds can use the preview
access tokens from Storyblok, but Production
builds should only ever use the public
access tokens. This is to ensure no unpublished content is accidentally revealed to the public. By default the environment variables from vault are set to point to the development environment and then overridden with the contextual environment plugin. For local development, you can override any of the environment variables as the netlify build plugins don't take effect when running netlify dev.
This project makes use of the NODE_ENV environment variable to run different builds. We also use .env
files to pass through configuration options which are then transformed by netlify plugins. By default the environment variables from vault are set to point to the development environment and then overridden with the contextual environment plugin. For local development, you can override any of the environment variables as the netlify build plugins don't take effect when running netlify dev.
You will need to be added to the Stanford ADAPT Team Netlify account. Contact a memeber on the team to receive access. Once you have been invited to the Team Netlify account, you will need to link your local enviroment.
If you do not have Netlify CLI locally setup, you will want to run the following command within your terminal:
npm install netlify-cli -g
Once Netlify CLI has been installed, you will want to log into your Netlify account:
netlify login
You'll be prompted to sign into your Netlify account and authorize your local Netlify CLI.
Then you can link your local project repository to Netlify by running:
netlify link
Currently Storyblok v2 doesn't allow accessing the environment with http, so to make it work, https has to be added to localhost. For your convenience we have created the certificate and key but your system may not trust this self signed cert. Once you have localhost up and running you can visit the url in the browser and proceed past the warning or you can add the certificate to your trusted list.
OSX: https://readwriteexercise.com/posts/trust-self-signed-certificates-macos/
To start:
npm run dev
npm run https-proxy-start
Or to choose your own ports:
netlify dev
npm run hps -- --target=64946 --source=3010
You will be prompted to select from four options. You will want to select the option:
> Use current git remote origin (https://github.com/SU-SWS/saa_alumni)
Once your local has been successfully link to Netlify, you can run the following command to streamline your local development experience:
netlify dev
Encountering issues with setup? Please refer to the official Netlify CLI documentation for further asssitance.
If you are experiencing issues with this module try reverting the feature first. If you are still experiencing issues try posting an issue on the GitHub issues page.
Environment variable file: .env
We are no longer using production
and development
environment variable files. We use the netlify-plugin-contextual-env plugin to support different environments. See below for more.
Netlify-plugin-contextual-env
We use this plugin to set the environment variables in the various different environments. See the plugin page for a full set of configuration options. We are use the prefix
option to separate out the different configuration.
The contextual-env plugin from Netlify runs on build time and does not provide runtime support for LAMBDA functions. To get those to work we have to add an additional plugin that inlines the values of the environment variables into your LAMBDA functions.
See: netlify-plugin-inline-functions-env
Prefix strategy
A non-prefixed version has to exist in order for the plugin to work. For example, GATSBY_TOKEN has to exist in order for DEPLOY_PREVIEW_GATSBY_TOKEN to work. The non-prefixed version of the environment variable is the default and then overridden with the plugin at build time. The default tokens should all point to the development environments so that branch deployes, dev environments, and build previews all use that token. We then use the PROD_
prefix to override the production environment builds.
Netlify should support only a minimal amount of environment variables in their UI. VAULT_ROLE_ID and VAULT_SECRET are required but all other environment variables should go into either a global folder or into the project specific folder.
The project specific folder for this website is secret/data/projects/adapt/alumni
As environment variables get contextualized through plugins, there is no need to separate out dev/prod variables into separate folders.
Vault source paths:
- 'secret/data/projects/adapt/alumni'
- 'secret/data/projects/adapt/certs'
Environment variables are stored (and versioned) in vault.stanford.edu. You can fetch them and have them written to .env
by running npm run vault
. You will need to add the vault role id and vault secret into the .env
file first. You can likely find those values in the Netlify environment variables UI. If you can't find them. Please ask another developer.
The script that fetches the secrets is 'netlify-plugin-vault-variables'. It is exectued by running npm run vault:local
.
When the script runs, it should only append new values to your .env
file. This means you can have your own local environment variables or overwrite ones that are coming from vault. You can change this so that vault overwrite all values by setting the environment variable VAULT_OVERWRITE=true.
All general development work should be based off of the dev
branch.
Branches should abide by the following branch name format: {branch-type}/JIRA-###_optional-description-of-task
where branch-type
is feature/
, task/
, or bug/
and JIRA-###
corresponds with the Jira ticket number.
This will ensure that features get labeled and organized correctly in the release and connect to Jira appropriately.
- Create branch from
dev
following the above outlined branch naming conventions. - Complete work in your branch.
- Create a pull request from your branch into
dev
branch. This will deploy a Netlify preview for your branch. - On PR approval, squash merge your branch with the following merge commit message format:
JIRA-### | Brief description of work completed
.
Pull requests against dev will need to pass status checks for the following:
- lint
- test
- Branch up to date with
dev
- Netlify build/deploy preview
Pull requests merged into dev will kickoff a Netlify branch deploy for the dev
branch.
To release code to production you will need to create a release branch from dev
and make a pull request to main
.
Including semver tags ([major]
, [minor]
, [patch]
) will automatically add a semver label to the PR which will
determine how to increment semver during release. If no label is provided it will default to patch
.
- Create branch from
dev
(or commit ref fromdev
) withrelease/
prefix and optional semver tag (e.g.release/completely-refactor-everything[major]
) - Create a pull request from your
release/my-cool-release
branch intomain
- On PR approval, do a standard merge commit into
main
Merges to main
will kickoff the following tasks:
- Semver version bump
- Publish github release
- Netlify production build and deploy
- Merge changes back into
dev
Hotfix workflows should only ever be used when there is a production bug that needs immediate attention and
there are changes in dev
that are not ready for deployment.
- Create a
hotfix/
branch frommain
- Complete the fix in your branch
- Create a pull request from your hotfix branch into
main
- On PR approval, squash merge your branch with the following merge commit message format:
JIRA-### | Brief description of hotfix
.
Depending on the nature your hotfix and the history of dev
you may need to to manually merge main
back into dev
to resolve merge conflicts.
To add codeclimate checks log in to codeclimate and add your repository with dev
as the default branch.
Go the codeclimate repo settings and install the Github pull request status updates. Now go back to Github
and make sure codeclimate
is added to required Status Checks for the dev
branch protection settings.
You are welcome to contribute functionality, bug fixes, or documentation to this module. If you would like to suggest a fix or new functionality you may add a new issue to the GitHub issue queue or you may fork this repository and submit a pull request. For more help please see GitHub's article on fork, branch, and pull requests
Megaprofile mocking can be enabled locally by running npm run dev:mock
, or by adding the following
environment variable:
MEGAPROFILE_MOCK=true
This will return mocked responses rather than call the Megaprofile Profile API.
Mocks for additional endpoints can be added in ./src/utilties/mockServer.js. Mock data should generally be stored in separate files in ./src/utilities/mocks.