diff --git a/.github/workflows/ci-docs.yml b/.github/workflows/ci-docs.yml new file mode 100644 index 00000000..8ce042be --- /dev/null +++ b/.github/workflows/ci-docs.yml @@ -0,0 +1,20 @@ +name: CI Documentation Checks + +on: + push: + branches: + - main + pull_request: + + +jobs: + lint-markdown: + name: Lint markdown + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + # This is the GitHub Actions-friendly port of the linter used in the Makefile. + - uses: gaurav-nelson/github-action-markdown-link-check@1.0.15 + with: + use-quiet-mode: 'yes' # errors only. + config-file: '.github/workflows/markdownlint-config.json' diff --git a/.github/workflows/markdownlint-config.json b/.github/workflows/markdownlint-config.json new file mode 100644 index 00000000..8682d838 --- /dev/null +++ b/.github/workflows/markdownlint-config.json @@ -0,0 +1,13 @@ +{ + "ignorePatterns" : [ + { + "pattern": "0005-example.md" + } + ], + "replacementPatterns": [ + { + "pattern": "^/", + "replacement": "{{BASEURL}}/" + } + ] +} diff --git a/Makefile b/Makefile index d3900ffd..be5771ba 100644 --- a/Makefile +++ b/Makefile @@ -39,6 +39,7 @@ __check_defined = \ infra-configure-network \ infra-format \ infra-lint \ + infra-lint-markdown \ infra-lint-scripts \ infra-lint-terraform \ infra-lint-workflows \ @@ -136,7 +137,10 @@ infra-check-compliance-checkov: ## Run checkov compliance checks infra-check-compliance-tfsec: ## Run tfsec compliance checks tfsec infra -infra-lint: infra-lint-scripts infra-lint-terraform infra-lint-workflows ## Lint infra code +infra-lint: infra-lint-markdown infra-lint-scripts infra-lint-terraform infra-lint-workflows ## Lint infra code + +infra-lint-markdown: ## Lint Markdown docs for broken links + ./bin/lint-markdown.sh infra-lint-scripts: ## Lint shell scripts shellcheck bin/** diff --git a/README.md b/README.md index baff380c..2c59ea49 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ This template assumes that you have an application to deploy. See [application r After downloading and installing the template into your project: -1. Follow the steps in [`docs/infra/README.md`](./docs/infra/README.md) to setup the infrastructure for your application. +1. Follow the steps in [infra/README.md](/infra/README.md) to setup the infrastructure for your application. 1. After setting up AWS resources, you can [set up GitHub Actions workflows](./template-only-docs/set-up-ci.md). 1. After configuring GitHub Actions, you can [set up continuous deployment](./template-only-docs/set-up-cd.md). 1. At any point, [set up your team workflow](./template-only-docs/set-up-team-workflow.md). diff --git a/bin/lint-markdown.sh b/bin/lint-markdown.sh new file mode 100755 index 00000000..8196a4be --- /dev/null +++ b/bin/lint-markdown.sh @@ -0,0 +1,18 @@ +#!/bin/bash + +# To make things simpler, ensure we're in the repo's root directory (one directory up) before +# running, regardless where the user is when invoking this script. + +# Grab the full directory name for where this script lives. +SCRIPT_DIR=$(readlink -f "$0" | xargs dirname) + +# Move up to the root since we want to do everything relative to that. Note that this only impacts +# this script, but will leave the user wherever they were when the script exists. +cd "${SCRIPT_DIR}/.." >/dev/null || exit 1 + + +LINK_CHECK_CONFIG=".github/workflows/markdownlint-config.json" + +# Recursively find all markdown files (*.md) in this directory. Pass them in as args to the lint +# command using the handy `xargs` command. +find . -name \*.md -print0 | xargs -0 -n1 markdown-link-check --config $LINK_CHECK_CONFIG diff --git a/docs/infra/set-up-infrastructure-tools.md b/docs/infra/set-up-infrastructure-tools.md index 040fecee..ecece2d7 100644 --- a/docs/infra/set-up-infrastructure-tools.md +++ b/docs/infra/set-up-infrastructure-tools.md @@ -22,7 +22,7 @@ Then install the version of Terraform you need. tfenv install 1.4.6 ``` -If you are unfamiliar with Terraform, check out this [basic introduction to Terraform](./introduction-to-terraform.md). +If you are unfamiliar with Terraform, check out this [basic introduction to Terraform](./intro-to-terraform.md). ### Install AWS CLI @@ -44,11 +44,17 @@ brew install gh ### Install linters -[Shellcheck](https://github.com/koalaman/shellcheck) and [actionlint](https://github.com/rhysd/actionlint) are optional utilites for running infrastructure linters locally. +We have several optional utilities for running infrastructure linters locally. These are run as part of the CI pipeline, therefore, it is often simpler to test them locally first. + +* [Shellcheck](https://github.com/koalaman/shellcheck) +* [actionlint](https://github.com/rhysd/actionlint) +* [markdown-link-check](https://github.com/tcort/markdown-link-check) ```bash + brew install shellcheck brew install actionlint +npm install -g markdown-link-check ``` ## AWS Authentication diff --git a/template-only-docs/application-requirements.md b/template-only-docs/application-requirements.md index d1630e9c..0ddf76d8 100644 --- a/template-only-docs/application-requirements.md +++ b/template-only-docs/application-requirements.md @@ -3,7 +3,7 @@ In order to use the template infrastructure, you need an application that meets the following requirements. * The application's source code lives in a folder that lives in the project root folder e.g. `/app`. -* The application folder needs to have a `Makefile` that has a build target `release-build` that takes in a Makefile variable `OPTS`, and passes those `OPTS` as options to the `docker build` command. The top level [Makefile](./Makefile) in this repo will call the application's `release-build` make target passing in release tags to tag the docker image with. +* The application folder needs to have a `Makefile` that has a build target `release-build` that takes in a Makefile variable `OPTS`, and passes those `OPTS` as options to the `docker build` command. The top level [Makefile](/Makefile) in this repo will call the application's `release-build` make target passing in release tags to tag the docker image with. * The web application needs to listen on the port defined by the environment variable `PORT`, rather than hardcode the `PORT`. This allows the infrastructure to configure the application to listen on a container port specified by the infrastructure. See [The Twelve-Factor App](https://12factor.net/) to learn more about designing applications to be portable to different infrastructure environments using environment variables. * The web application needs to have a health check endpoint at `/health` that returns an HTTP 200 OK response when the application is healthy and ready to accept requests. * The Docker image needs to have `wget` installed. This is used in the container task defintion's healthcheck configuration in order to ping the application's `/health` endpoint. If you want to use a different healthcheck command (e.g. `curl`) then you'll need to modify the `healthCheck` configuration in the `aws_ecs_task_definition` resource in [modules/service/main.tf](/infra/modules/service/main.tf). @@ -22,7 +22,7 @@ If your application needs a database, it must also: ## Example Application -The infra template includes an example "hello, world" application that works with the template. This application is fully deployed and can be viewed at the endpoint . The source code for this test application is at . +The infra template includes an example "hello, world" application that works with the template. This application is fully deployed and can be viewed at the endpoint . The source code for this test application is at . ## Template Applications