Verd Dev Web App

Portfolio website for Verderese Development. This project is meant to serve two main purposes:

1. Provide the source code for the Verderese Development web application.
2. Showcase the development process and best practices for a modern web application.

Local Development

Running the Application on the Host Machine

1. Ensure Docker is installed on your machine.
2. Ensure nodenv is installed on your machine.
3. Copy .env.local.example to .env.local and fill in the required values.
4. Install the correct version of Node and upgrade NPM

   nodenv install -s
   npm install -g npm

5. Run the dependency containers.

   npm run docker:local

6. Run the web application. As an alternative, you can run the "Next Dev" WebStorm run configuration.

   npm run dev

Git Development Workflow

1. Install pre-commit hooks. This will ensure all linting passes before committing to git.

   npm run git:install-hooks

2. Create a branch off of latest develop

   git checkout develop &&
   git fetch origin &&
   git reset --hard origin/develop &&
   git checkout -b <branch_name>

3. Commit and push early and often

4. Ensure your branch is up-to-date with develop

   git fetch origin &&
   git merge origin/develop &&
   # Resolve merge conflicts if they come up
   git push

   (You may need to git push --set-upstream origin <branchname>)

5. Create a pull request in GitHub with the issue number at the end of the title.

6. Ensure all CI checks pass and request reviewers.

7. Once someone approves the PR, ensure you are still up-to-date with develop.

8. Merge the PR

Commit Message

It's important that we maintain a clean and readable commit history on the develop branch in each of our Git repos. Each commit on a branch that is ready to be merged into develop should adhere to the following guidelines:

• Commits should be able to stand alone as a single unit of change and not (intentionally) introduce any breakages or undesired changes to production code paths - they should generally encapsulate a single logical change or several small, closely-related changes.
• Messages must have a summary line that is prefixed with the GitHub issue ID. If a given change does not have an associated ticket, create one or (for extremely trivial changes) use 000 as a placeholder.
• Messages must be wrapped at 72 characters. The summary line must not exceed 50 characters and must be followed by a blank line if including a message body.
• Messages should be concise and meaningful, including as much detail as needed to convey the purpose of the change (bug fix, code cleanup, feature, etc), how the specific issue was addressed, and any limitations/caveats or other notable points - they should not, however, be overly verbose or include too much technical detail.

Example of a well-structured commit message

Summary plus GitHub issue number

More detailed explanatory text. Wrap it to 72 characters. You may omit
the body entirely; otherwise, the blank line separating the summary
from the body is critical.

Write your commit message in the imperative: "Fix bug" and not "Fixed
bug" or "Fixes bug." This convention matches up with commit messages
generated by commands like git merge and git revert.

Each paragraph should be separated from the others by a blank line.
- Bullet points are okay, too.
- Typically a hyphen or asterisk is used for the bullet, followed by a
 single space. Use a hanging indent.

Note: It is helpful to setup your text editor or IDE that you use to write commit messages to have a visual guide at 50 and 72 characters.

Pull Request

A pull request ("PR") should almost always introduce a non-breaking change, with each commit very clear as to what it does.

The title of a pull request should be no more than 72 characters and should follow this format. Note that this format is not done automatically in most cases.

Short description of the change introduced

The body should have a description of the changes, and should include the message "Fixes <issue_number>" inside it, so that it links the PR to the GitHub issue.

Wherever possible, try to keep your pull requests small, and keep distinct changes isolated from each other. This will be a big help in speeding up development and code review and reducing the surface area for problems. There are a couple of reasons for this, and the main ones are outlined below.

External Resources

Git 50/72: the rule of well formed Git commit messages

The Art of the Commit

Stages and Application Lifecycle

Infrastructure

The infrastructure for this project is managed via Terraform. A single project is used to host dev, staging, and production with a shared DB instance in order to reduce costs. In an enterprise environment, it would be best to separate these environments into their own projects.

First Time Setup

If you have cloned this project and are setting up a new GCP project to host the web application, you will need to make a few manual changes.

1. Ensure the Google Cloud CLI is installed on your machine. Homebrew is the easiest way to install on a Mac. Otherwise, follow the instructions in the Install the gcloud CLI guide
2. Create a GCP Billing Account. If this is your first time doing this, you should be eligible for the $300 in free credit.
3. Ensure Terraform is installed on your machine. Homebrew is the easiest way to install on a Mac. Otherwise, follow the instructions in the Install Terraform guide
4. Log in to the Google Cloud CLI and set the application default credentials.

   gcloud auth login
   gcloud auth application-default login

5. Copy ops/terraform/terraform.tfvars.example to ops/terraform/terraform.tfvars and fill in the required values.
6. Copy ops/terraform/bootstrap/terraform.tfvars.example to ops/terraform/bootstrap/terraform.tfvars and fill in the required values.
7. Update the bucket name at ops/terraform/main.tf:9 to be {project}-bucket-tfstate. The provider block of terraform does not support variables.
8. Run the bootstrap terraform script to create the GCP project and enable the required APIs. The state file for this script should be force checked into the repository. TODO: See if there is a better way to handle this.

   npm run terraform:bootstrap

9. Run the main terraform script to create the infrastructure.

   npm run terraform:apply

Updating Infrastructure

If you have already set up the infrastructure and need to make changes, always run a plan first to see what changes will be made.

npm run terraform:plan

Once you are happy with the changes, apply them.

npm run terraform:apply

TODO: Leverage Atlantis to manage Terraform changes via Pull Requests.