Merge branch 'main' into wb-edit

.env.example

@@ -1,4 +1,4 @@
-BUILD_MODE=local # local / demo / production
+BUILD_MODE=local # local / pr-preview / production
 
 LOCAL_ENABLE_REDIRECTS=Yes
 LOCAL_ENABLE_TAGS=Yes

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,7 @@
+<!-- Enter 'x' into the checkbox to confirm (if applicable). -->
+
+* [ ] I have spellchecked my content using Microsoft Word, Grammarly, or otherwise.
+* [ ] If required, update the [DEA Tech Alerts and Changelog](TechAlertsChangelog) and the [DEA Sandbox Updates banner](SandboxUpdatesBanner).
+
+[TechAlertsChangelog]: https://github.com/GeoscienceAustralia/dea-knowledge-hub/blob/main/docs/tech-alerts-changelog/_tech_alerts_changelog.md
+[SandboxUpdatesBanner]: https://bitbucket.org/geoscienceaustralia/datakube-apps/src/64c28bbf3d0e019d8940547a22f78b9bfd58d739/clusters/dea-sandbox/sandbox.yaml

.github/workflows/deploy-pr-preview.yaml

@@ -0,0 +1,114 @@
+name: Deploy to PR Preview
+
+on:
+  pull_request:
+    branches:
+      - main
+
+env:
+  PR_PREVIEW_PULL_REQUEST_NUMBER: ${{github.event.pull_request.number}}
+  PR_PREVIEW_SUBDOMAIN: pr-${{github.event.pull_request.number}}-preview
+  PR_PREVIEW_DEPLOY_LOG_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+  PR_PREVIEW_BUCKET: s3://khpreview.dea.ga.gov.au
+  PR_PREVIEW_SKIP_COMMAND_1: "[no preview]"
+  PR_PREVIEW_SKIP_COMMAND_2: "[skip preview]"
+
+permissions:
+  id-token: write # For requesting the JWT used by OIDC Authentication
+  issues: write
+  pull-requests: write
+
+jobs:
+  pr-preview:
+    runs-on: ubuntu-latest
+    if: |
+      !contains(github.event.head_commit.message, '${{ env.PR_PREVIEW_SKIP_COMMAND_1 }}') &&
+      !contains(github.event.head_commit.message, '${{ env.PR_PREVIEW_SKIP_COMMAND_2 }}') &&
+      !contains(github.event.pull_request.title, '${{ env.PR_PREVIEW_SKIP_COMMAND_1 }}') &&
+      !contains(github.event.pull_request.title, '${{ env.PR_PREVIEW_SKIP_COMMAND_2 }}') &&
+      !contains(github.event.pull_request.body, '${{ env.PR_PREVIEW_SKIP_COMMAND_1 }}') &&
+      !contains(github.event.pull_request.body, '${{ env.PR_PREVIEW_SKIP_COMMAND_2 }}')
+
+    strategy:
+      matrix:
+        python-version: ["3.11"]
+        node-version: [18.x]
+
+    steps:
+      - name: Find Comment
+        uses: peter-evans/find-comment@v3
+        id: find-comment
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          comment-author: 'github-actions[bot]'
+          body-includes: PR Preview
+
+      - name: "Comment: PR Preview is deploying"
+        uses: peter-evans/create-or-update-comment@v4
+        with:
+          issue-number: ${{github.event.pull_request.number}}
+          comment-id: ${{ steps.find-comment.outputs.comment-id }}
+          edit-mode: replace
+          body: |
+            ## :hourglass: PR Preview is deploying ...
+
+            <table>
+                <tr>
+                    <td><strong>Deploy log:</strong></td>
+                    <td><a href="${{ env.PR_PREVIEW_DEPLOY_LOG_URL }}">View the log</a></td>
+                </tr>
+            </table>
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Pull latest from submodules
+        run: git submodule foreach git pull origin stable
+          # This doesn't update the submodule to the latest commit on the origin; therefore, you should manually do this on a semi-regular basis.
+
+      - name: Install Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'  # Use pip to cache the installed dependencies
+
+      - name: Install dependencies
+        run: ./install-dependencies.sh
+
+      - name: Build site
+        env:
+          BUILD_MODE: pr-preview
+        run: ./build-pr-preview.sh
+
+      - name: Configure AWS credentials via OIDC
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: arn:aws:iam::538673716275:role/github-actions-dea-knowledge-hub-prs
+          aws-region: ap-southeast-2
+
+      - name: Deploy preview site
+        run: |
+          aws s3 sync --delete output "$PR_PREVIEW_BUCKET/$PR_PREVIEW_SUBDOMAIN"
+
+      - name: "Update Comment: PR Preview is ready"
+        uses: peter-evans/create-or-update-comment@v4
+        with:
+          issue-number: ${{github.event.pull_request.number}}
+          comment-id: ${{ steps.find-comment.outputs.comment-id }}
+          edit-mode: replace
+          body: |
+            ## :star2: PR Preview is ready!
+
+            <table>
+                <tr>
+                    <td><strong>Preview site:</strong></td>
+                    <td><a href="https://${{ env.PR_PREVIEW_SUBDOMAIN }}.khpreview.dea.ga.gov.au/">${{ env.PR_PREVIEW_SUBDOMAIN }}.khpreview.dea.ga.gov.au</a></td>
+                </tr>
+                <tr>
+                    <td><strong>Deploy log:</strong></td>
+                    <td><a href="${{ env.PR_PREVIEW_DEPLOY_LOG_URL }}">View the log</a></td>
+                </tr>
+            </table>
+            

.github/workflows/deploy-production.yaml

@@ -3,7 +3,7 @@ name: Deploy to Production
 on:
   workflow_dispatch:
   repository_dispatch:
-    types: [republish-docs] # Triggered from the dea-notebooks repo
+    types: [republish-docs] # Triggered by the dea-notebooks repo - https://github.com/GeoscienceAustralia/dea-notebooks/blob/develop/.github/workflows/trigger_docs.yaml
   push:
     branches: [main]
 
@@ -12,25 +12,30 @@ permissions:
 
 jobs:
   publish:
-    name: Publish
     runs-on: ubuntu-latest
+
     strategy:
       matrix:
         python-version: ["3.11"]
         node-version: [18.x]
+
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
           submodules: true
 
+      - name: Pull latest from submodules
+        run: git submodule foreach git pull origin stable
+          # This doesn't update the submodule to the latest commit on the origin; therefore, you should manually do this on a semi-regular basis.
+
       - name: Install Python ${{ matrix.python-version }}
         uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Install requirements
-        run: ./install-production.sh
+      - name: Install dependencies
+        run: ./install-dependencies.sh
 
       - name: Build site
         env:
@@ -41,7 +46,7 @@ jobs:
         if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
         uses: aws-actions/configure-aws-credentials@v2
         with:
-          role-to-assume: arn:aws:iam::538673716275:role/github-actions-dea-docs
+          role-to-assume: arn:aws:iam::538673716275:role/github-actions-dea-knowledge-hub
           aws-region: ap-southeast-2
 
       - name: Deploy site

.gitmodules

@@ -3,4 +3,4 @@
 	url = https://github.com/GeoscienceAustralia/dea-notebooks.git
 	branch = stable
 	shallow = true
-	ignore = untracked
+	ignore = dirty

Dockerfile

@@ -10,7 +10,7 @@ RUN mkdir -p /setup
 RUN mkdir -p /docs
 RUN mkdir -p /output
 
-COPY requirements.txt /setup
+COPY docs/requirements.txt /setup
 RUN pip install -r /setup/requirements.txt
 
 COPY docs /docs

Makefile

@@ -6,13 +6,13 @@ run:
 	make start
 
 build:
-	docker build -t dea-docs .
+	docker build -t dea-knowledge-hub .
 
 rebuild:
-	docker build --no-cache -t dea-docs .
+	docker build --no-cache -t dea-knowledge-hub .
 
 start:
-	docker run -it --rm --name dea-docs --publish 8062:8062 --volume ./docs/notebooks:/docs/notebooks --volume ./output:/output --env-file .env dea-docs \
+	docker run -it --rm --name dea-knowledge-hub --publish 8062:8062 --volume ./docs/notebooks:/docs/notebooks --volume ./output:/output --env-file .env dea-knowledge-hub \
 	| grep --invert-match --regexp "WARNING.*Document headings start at" \
 	| grep --invert-match --regexp "WARNING.*duplicate label" \
 	| grep --invert-match --regexp "^copying images..." \
@@ -21,7 +21,10 @@ start:
 	| grep --invert-match --regexp ".*GET /_images.*"
 
 ssh:
-	docker exec -it dea-docs /bin/sh
+	docker exec -it dea-knowledge-hub /bin/sh
 
 test-redirects:
 	npx mocha ./aws/cloudfront/functions/*.js
+
+clean:
+	rm -rf ./output

README.md

@@ -1,3 +1,7 @@
 # DEA Knowledge Hub
 
-To contribute content to this site, please [follow the publication process and git workflow](https://geoscienceau.sharepoint.com/:w:/r/sites/DEA/_layouts/15/Doc.aspx?sourcedoc=%7BE75F31A8-1648-4DA3-9E36-9BB8135921B2%7D&file=DEA%20Publication%20Process.docx&action=default&mobileredirect=true).
+This is the repository for the [DEA Knowledge Hub](https://knowledge.dea.ga.gov.au/) website.
+
+It was previously called 'DEA Docs' or 'dea-docs'.
+
+To contribute content to this site, please follow the [publication process and git workflow](https://geoscienceau.sharepoint.com/:w:/r/sites/DEA/_layouts/15/Doc.aspx?sourcedoc=%7BE75F31A8-1648-4DA3-9E36-9BB8135921B2%7D&file=DEA%20Publication%20Process.docx&action=default&mobileredirect=true).

aws/cloudfront/functions/redirects.js

@@ -1,17 +1,38 @@
+// AWS CloudFront redirects
+// Learn how to test and deploy these redirects:
+// https://docs.dev.dea.ga.gov.au/public_services/dea_knowledge_hub/aws_redirects.html
+
 // This function handles redirect logic
 
 async function handler(event) {
     const request = event.request;
+    const host = event.request.headers.host.value;
     const uri = event.request.uri;
+
     const deaToolsSourceCodePattern = /dea_tools\/(.*)\.py$/;
     const indexHtmlPattern = /\/index\.html$/g;
     const filetypeExtensionsPattern = /\.(html|rst|md|ipynb|py)$/g;
 
+    const docsHost = "docs.dea.ga.gov.au";
+    const knowledgeHost = "knowledge.dea.ga.gov.au";
+
     const status301MovedPermanently = {
         statusCode: 301,
         statusDescription: "Moved Permanently"
     };
 
+    // Redirect subdomain from 'docs' to 'knowledge'. E.g. "docs.dea.ga.gov.au" => "knowledge.dea.ga.gov.au"
+
+    if (host === docsHost) {
+        return Object.assign(status301MovedPermanently, {
+            headers: {
+                location: {
+                    value: "https://" + knowledgeHost + uri
+                }
+            }
+        });
+    }
+
     // Redirect DEA Tools source code URLs to the relevant 'automodule' page generated from the source code.
     // E.g. "/notebooks/Beginners_guide/Tools/dea_tools/plotting.py" => "/notebooks/Tools/gen/dea_tools.plotting/"
     // E.g. "/notebooks/Interactive_apps/Tools/dea_tools/app/animations.py" => "/notebooks/Tools/gen/dea_tools.app.animations/"
@@ -57,4 +78,5 @@ async function handler(event) {
 
     return request;
 }
+
 module.exports = { handler };

aws/cloudfront/functions/test.js

@@ -2,8 +2,26 @@
 const { handler } = require("./redirects.js");
 var assert = require("assert");
 
-describe("Test redirect occurs", () => {
-    const tests = [
+const docsHost = "docs.dea.ga.gov.au";
+const knowledgeHost = "knowledge.dea.ga.gov.au";
+
+// Create a minimum event object matching the structure that AWS CloudFront uses.
+// The real thing contains many more fields, this is just what we use.
+function requestTemplate(host, uri) {
+    return {
+        request: {
+            uri: uri,
+            headers: {
+                host: {
+                    value: host
+                }
+            }
+        }
+    };
+}
+
+describe("Redirect Tests", () => {
+    const r1 = [
         { uri: "/index.html", expected: "/" },
         { uri: "/page/index.html", expected: "/page/" },
         { uri: "/category/page.html", expected: "/category/page/" },
@@ -22,39 +40,52 @@ describe("Test redirect occurs", () => {
         }
     ];
 
-    tests.forEach(({ uri, expected }) => {
-        let input = { request: { uri: uri } };
-        it(`Correctly redirects ${uri} to ${expected}`, async () => {
-            const res = await handler(input);
+    r1.forEach(({ uri, expected }, index) => {
+        const n = index + 1;
+        it(`R1.${n}. Redirects ${uri} to ${expected}`, async () => {
+            const res = await handler(requestTemplate(knowledgeHost, uri));
 
             assert.equal(res.headers.location.value, expected);
         });
     });
 });
 
-describe("Test redirect doesn't occur", () => {
-    const tests = [
-        {
-            uri: "/data/product/dea-coastlines/"
-        },
-        {
-            uri: "/data/product/dea-coastlines/?tab=overview"
-        },
-        {
-            uri: "/notebooks/Tools/gen/dea_tools.plotting/"
-        },
-        {
-            uri: "/notebooks/Tools/gen/dea_tools.app.animations/"
-        }
+describe("Don't Redirect Tests", () => {
+    const r2 = [
+        "/data/product/dea-coastlines/",
+        "/data/product/dea-coastlines/?tab=overview",
+        "/notebooks/Tools/gen/dea_tools.plotting/",
+        "/notebooks/Tools/gen/dea_tools.app.animations/"
     ];
 
-    tests.forEach(({ uri }) => {
-        let input = { request: { uri: uri } };
-        let expected = { uri: uri };
-        it(`Doesn't redirect ${uri}`, async () => {
-            const res = await handler(input);
+    r2.forEach((uri, index) => {
+        const n = index + 1;
+        it(`R2.${n}. Doesn't redirect ${uri}`, async () => {
+            const res = await handler(requestTemplate(knowledgeHost, uri));
+
+            assert.ok(!res.hasOwnProperty("statusCode"));
+            assert.ok(!res.hasOwnProperty("statusDescription"));
+        });
+    });
+});
+
+describe("Domain redirection tests", () => {
+    const r3 = [
+        "/",
+        "/index.html",
+        "/data/product/dea-coastlines/",
+        "/data/product/dea-coastlines/?tab=overview"
+    ];
+
+    r3.forEach((uri, index) => {
+        const docsUri = "https://" + docsHost + uri;
+        const knowledgeUri = "https://" + knowledgeHost + uri;
+
+        const n = index + 1;
+        it(`R3.${n}. Redirects from ${docsUri} to ${knowledgeUri}`, async () => {
+            const res = await handler(requestTemplate(docsHost, uri));
 
-            assert.deepStrictEqual(res, expected);
+            assert.equal(res.headers.location.value, knowledgeUri);
         });
     });
 });