initial commit

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,33 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ""
+labels: ""
+assignees: ""
+---
+
+### Describe the bug
+
+A clear and concise description of what the bug is.
+
+### To reproduce
+
+Steps to reproduce the behavior:
+
+1. Deploy this project using ...
+2. View output/logs/configuration on ...
+3. See error
+
+### Expected behavior
+
+A clear and concise description of what you expected to happen.
+
+### Your environment
+
+- Version/release of this project or specific commit
+<!-- - Version/release of any relevant project languages -->
+- Target deployment platform
+
+### Additional context
+
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ""
+labels: ""
+assignees: ""
+---
+
+### Is your feature request related to a problem? Please describe
+
+A clear and concise description of what the problem is. Ex. I'm always frustrated when ...
+
+### Describe the solution you'd like
+
+A clear and concise description of what you want to happen.
+
+### Describe alternatives you've considered
+
+A clear and concise description of any alternative solutions or features you've considered.
+
+### Additional context
+
+Add any other context or screenshots about the feature request here.

.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: daily
+    groups:
+      actions:
+        update-types:
+          - "major"
+          - "minor"
+          - "patch"

.github/pull_request_template.md

@@ -0,0 +1,12 @@
+### Proposed changes
+
+Describe the use case and detail of the change. If this PR addresses an issue on GitHub, make sure to include a link to that issue using one of the [supported keywords](https://docs.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue) here in this description (not in the title of the PR).
+
+### Checklist
+
+Before creating a PR, run through this checklist and mark each as complete.
+
+- [ ] I have read the [`CONTRIBUTING`](https://github.com/{{REPOSITORY_OWNER}}/{{REPOSITORY_URL}}/blob/main/CONTRIBUTING.md) document
+- [ ] If applicable, I have added tests that prove my fix is effective or that my feature works
+- [ ] If applicable, I have checked that any relevant tests pass after adding my changes
+- [ ] I have updated any relevant documentation ([`README.md`](https://github.com/{{REPOSITORY_OWNER}}/{{REPOSITORY_URL}}/blob/main/README.md) and [`CHANGELOG.md`](https://github.com/{{REPOSITORY_OWNER}}/{{REPOSITORY_URL}}/blob/main/CHANGELOG.md))

.github/workflows/docs-build-push.yml

@@ -0,0 +1,292 @@
+name: Docs Build Push
+
+on:
+  workflow_call:
+    secrets:
+      AZURE_CREDENTIALS:
+        required: true
+      AZURE_KEY_VAULT:
+        required: true
+    inputs:
+      environment:
+        description: "This will be appended to the baseURL for for production builds. For example, main docs will be `/` where agent would be `/nginx-agent`"
+        required: false
+        default: preview
+        type: string
+      production_url_path:
+        description: "This will be appended to the baseURL for for production builds. For example, main docs will be `/` where agent would be `/nginx-agent`"
+        required: true
+        type: string
+      preview_url_path:
+        description: "Appended to the baseURL for PR preview builds"
+        required: true
+        type: string
+      docs_source_path:
+        description: "Directory of built docs files. Hugo default would be `./public/`"
+        required: true
+        type: string
+      docs_build_path:
+        description: "Directory where hugo or sphinx build command should be run from"
+        required: false
+        type: string
+        default: ./
+      doc_type:
+        type: string
+        description: "Type of source docs. Currently supports 'hugo' and 'sphinx'"
+        default: hugo
+
+env:
+  GO_VERISON: "1.21" # Go version used for `hugo mod get`
+  HUGO_VERSION: "0.115.3" # Hugo version used for building docs
+  THEME_MODULE: "github.com/nginxinc/nginx-hugo-theme" # Name of source repo for module. For example; github.com/nginxinc/nginx-hugo-theme
+  THEME_VERSION: "0.41.10" # Version of theme module. For example; 0.41.6
+
+  PR_NUMBER: ${{github.event.pull_request.number}}
+
+  # environments
+  DOMAIN_PREVIEW: "frontdoor-test-docs.nginx.com"
+  DOMAIN_DEV: "docs-dev.nginx.com"
+  DOMAIN_STAGING: "docs-staging.nginx.com"
+  DOMAIN_PROD: "docs.nginx.com"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      # Remapping of inputs to envs
+      PRODUCTION_URL_PATH: ${{inputs.production_url_path}}
+      PREVIEW_URL_PATH: ${{inputs.preview_url_path}}
+      DOCS_SOURCE_PATH: ${{inputs.docs_source_path}}
+      EVENT_ACTION: ${{github.event.action}}
+      DEPLOYMENT_ENV: ${{inputs.environment}}
+
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    steps:
+      - name: Validate environment inputs
+        run: |
+          if [[ -z "${DEPLOYMENT_ENV}" ]]; then
+               # for use in this step
+            export DEPLOYMENT_ENV="preview"
+
+            # for use in subsequent steps
+            echo "DEPLOYMENT_ENV=preview" >> "$GITHUB_ENV"
+          fi
+
+          if [[ ! "${DEPLOYMENT_ENV}" =~ ^(dev|staging|prod|preview)$ ]]; then
+            echo "::error::Invalid environment input: ${DEPLOYMENT_ENV}. Must be one of dev, staging, prod, preview"
+            exit 1
+          fi
+
+          if [[ "${DEPLOYMENT_ENV}" == "preview" && -z "${PR_NUMBER}" ]]; then
+            echo "PR_NUMBER=${GITHUB_SHA::7}" >> "$GITHUB_ENV"
+            echo "::notice::PR_NUMBER set to short commit hash: ${GITHUB_SHA::7}"
+          fi
+
+          if [[ -z "${GITHUB_SHA}" ]]; then
+            echo "::error::GITHUB_SHA not set. This shouldn't happen!"
+            exit 1
+          fi
+
+      - name: Set deployment domain
+        id: deployment
+        run: |
+          case ${DEPLOYMENT_ENV} in
+            dev)
+              DOMAIN="${DOMAIN_DEV}"
+              ;;
+            staging)
+              DOMAIN="${DOMAIN_STAGING}"
+              ;;
+            prod)
+              DOMAIN="${DOMAIN_PROD}"
+              ;;
+            preview)
+              DOMAIN="${DOMAIN_PREVIEW}"
+              ;;
+          esac
+
+          echo "DEPLOYMENT_DOMAIN=${DOMAIN}" >> $GITHUB_ENV
+
+      - name: Azure login
+        uses: azure/login@6c251865b4e6290e7b78be643ea2d005bc51f69a # v2.1.1
+        with:
+          creds: ${{ secrets.AZURE_CREDENTIALS }}
+
+      - name: Retrieve secrets from Keyvault
+        id: keyvault
+        uses: azure/cli@965c8d7571d2231a54e321ddd07f7b10317f34d9 # v2.0.0
+        with:
+          inlineScript: |
+            secrets_get=(resourceGroupName cdnProfileName cdnName accountName)
+            for secret_get in ${secrets_get[@]}
+            do
+              value=$(az keyvault secret show --name $secret_get --vault-name ${{ secrets.AZURE_KEY_VAULT }} --query value --output tsv)
+              echo "::add-mask::$value"
+              echo "$secret_get=$value" >> $GITHUB_OUTPUT
+            done
+
+      - name: Checkout docs content
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.7.1
+
+        ### Hugo builds
+
+      - name: Setup Go
+        uses: actions/setup-go@0a12ed9d6a96ab950c8f026ed9f722fe0da7ef32 # v5.0.2
+        if: inputs.doc_type == 'hugo'
+        with:
+          go-version: ${{env.GO_VERISON}}
+
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
+        if: inputs.doc_type == 'hugo'
+        with:
+          hugo-version: ${{env.HUGO_VERSION}}
+
+      - name: Build Hugo for PR preview
+        if: inputs.doc_type == 'hugo' && (github.event.action == 'synchronize' || github.event.action == 'opened' || env.DEPLOYMENT_ENV == 'preview')
+        working-directory: ${{inputs.docs_build_path}}
+        run: |
+          hugo mod get -v "$THEME_MODULE@v$THEME_VERSION"
+          hugo --gc -e production --baseURL="https://${DEPLOYMENT_DOMAIN}${PREVIEW_URL_PATH}/${PR_NUMBER}"
+
+      - name: Build Hugo for environment
+        working-directory: ${{inputs.docs_build_path}}
+        if: inputs.doc_type == 'hugo' && env.DEPLOYMENT_ENV != 'preview'
+        run: |
+          hugo mod get "$THEME_MODULE@v$THEME_VERSION"
+          hugo --gc -e production --baseURL="https://${DEPLOYMENT_DOMAIN}${PRODUCTION_URL_PATH}"
+
+        ### Sphinx builds
+
+      - name: Setup Sphinx
+        uses: actions/setup-python@39cd14951b08e74b54015e9e001cdefcf80e669f # v5.1.1
+        if: inputs.doc_type == 'sphinx'
+        with:
+          python-version: "3.9"
+
+      - name: Install python dependencies
+        if: inputs.doc_type == 'sphinx'
+        run: pip install -r requirements.txt
+
+      - name: Setup Gnupg directories
+        if: inputs.doc_type == 'sphinx'
+        run: |
+          mkdir -p /home/runner/.gnupg
+          chmod 700 /home/runner/.gnupg
+
+      - name: Build Sphinx for PR preview and production
+        working-directory: ${{inputs.docs_build_path}}
+        if: inputs.doc_type == 'sphinx'
+        run: |
+          make deploy
+
+      ### Azure upload
+
+      - name: Azure upload PR preview
+        uses: azure/cli@965c8d7571d2231a54e321ddd07f7b10317f34d9 # v2.0.0
+        if: github.event.action == 'synchronize' || github.event.action == 'opened' || env.DEPLOYMENT_ENV == 'preview'
+        with:
+          inlineScript: |
+            cd ${{inputs.docs_build_path}} \
+            && az storage blob upload-batch \
+                 -s $DOCS_SOURCE_PATH \
+                 -d '$web' \
+                 --destination-path "dev/${{github.repository}}/previews/${PR_NUMBER}" \
+                 --account-name ${{steps.keyvault.outputs.accountName}} \
+                 --overwrite \
+                 --content-cache-control "max-age=3600" \
+                 --auth-mode login
+
+                 az afd endpoint purge \
+                  --resource-group ${{steps.keyvault.outputs.resourceGroupName}} \
+                  --profile-name ${{steps.keyvault.outputs.cdnProfileName}} \
+                  --endpoint-name ${{steps.keyvault.outputs.cdnName}} \
+                  --domains $DOMAIN_PREVIEW \
+                  --content-paths "${PREVIEW_URL_PATH}/*" \
+                  --no-wait
+
+      - name: Azure upload to specified environment
+        uses: azure/cli@965c8d7571d2231a54e321ddd07f7b10317f34d9 # v2.0.0
+        if: env.DEPLOYMENT_ENV != 'preview'
+        with:
+          inlineScript: |
+            cd ${{inputs.docs_build_path}} \
+            && az storage blob upload-batch \
+                 -s $DOCS_SOURCE_PATH \
+                 -d '$web' \
+                 --destination-path "${DEPLOYMENT_ENV}/${{github.repository}}/latest/" \
+                 --account-name ${{steps.keyvault.outputs.accountName}} \
+                 --overwrite \
+                 --content-cache-control "max-age=3600" \
+                 --auth-mode login
+
+               az afd endpoint purge \
+                  --resource-group ${{steps.keyvault.outputs.resourceGroupName}} \
+                  --profile-name ${{steps.keyvault.outputs.cdnProfileName}} \
+                  --endpoint-name ${{steps.keyvault.outputs.cdnName}} \
+                  --domains $DEPLOYMENT_DOMAIN \
+                  --content-paths "${PRODUCTION_URL_PATH}/*" \
+                  --no-wait
+
+      - name: Azure logout
+        run: |
+          az logout
+        if: always()
+
+      ### PR preview comment
+
+      - name: PR preview comment
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        if: env.DEPLOYMENT_ENV == 'preview' && (github.event.action == 'synchronize' || github.event.action == 'opened')
+        with:
+          script: |
+            // If a comment already exists, skip
+            const { data: comments } = await github.rest.issues.listComments({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+            });
+
+            const existingComment = comments.find(comment => comment.user.login === 'github-actions[bot]' && comment.body.includes('Deploy Preview'));
+
+            if (existingComment) {
+              core.info('Preview comment already exists. Skipping...');
+              return;
+            }
+
+            const previewHostname = process.env.DOMAIN_PREVIEW;
+            const previewUrlPath = process.env.PREVIEW_URL_PATH;
+            const prNumber = context.payload.pull_request.number;
+
+            const previewUrl = `https://${previewHostname}${previewUrlPath}/${prNumber}/`;
+
+            const body = `### <span aria-hidden="true">✅</span> Deploy Preview will be available once build job completes!
+
+            |  Name | Link |
+            |:-:|------------------------|
+            |<span aria-hidden="true">😎</span> Deploy Preview | [${previewUrl}](${previewUrl}) |
+            ---`;
+
+            await github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: body,
+            });
+
+      - name: Summary
+        # TODO(dani): Extract this into a reusable Markdown template for comments and summaries?
+        run: |
+          echo "### Deployment Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "| Task | Result |" >> $GITHUB_STEP_SUMMARY
+          echo "|---|---|" >> $GITHUB_STEP_SUMMARY
+          echo "| Deployment environment | \`${DEPLOYMENT_ENV}\`|" >> $GITHUB_STEP_SUMMARY
+          if [[ "${DEPLOYMENT_ENV}" == "preview" ]]; then
+            echo "| Preview URL | [https://${DOMAIN_PREVIEW}${PREVIEW_URL_PATH}/${PR_NUMBER}/](https://${DOMAIN_PREVIEW}${PREVIEW_URL_PATH}/${PR_NUMBER}/) |" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "| Production URL | [https://${DEPLOYMENT_DOMAIN}${PRODUCTION_URL_PATH}](https://${DEPLOYMENT_DOMAIN}${PRODUCTION_URL_PATH}) |" >> $GITHUB_STEP_SUMMARY
+          fi
+
+        # TODO(dani): Add more details to the summary