Merge pull request #3339 from EnterpriseDB/release/2022-11-10

Release: 2022-11-10

install_template/README.md

@@ -49,7 +49,8 @@ After a template file is found, no rules are enforced on how that template shoul
 #### `/templates/platformBase/base.njk`
 
 - All templates ultimately should inherit from this file. This is a good place to write copy that needs to be shared by all docs, regardless of the product being installed
-- 3 blocks are currently available:
+- several blocks are currently defined in this base file, including:
+  - `frontmatter` — This is where additional frontmatter keys can be defined (the base template defines title and navTitle) - this is particularly useful for redirects and deployment rules, see below.
   - `prerequisites` — This is where information like adding EDB repos will go
   - `installCommand` — This is where the command to actually install the product will go
   - `postinstall` — This is where commands like starting the EPAS server will go
@@ -107,3 +108,33 @@ We also use global variables to trigger conditionals:
 For small template systems, this system works well enough. But as the number of templates increases, this becomes harder to understand. In this case, we need to search through the template files to find out where the variables are being used. Fortunately, they are used just once, but it's not hard to imagine multiple (and exclusive) conditionals that are hard to read, modify and debug.
 
 It's almost always better to use one of the other techniques than fall back on conditionals triggered by global variables.
+
+## Deployment rules
+
+The deployment script (`npm run install-docs:deploy`) can use two sources of information on where to deploy the final MDX files:
+
+1. A rule defined within the deployment script itself (`deploy.mjs`). 
+2. (RECOMMENDED) A frontmatter key (`deployPath`) written to the generated MDX file itself. Ex:
+
+   ```yaml
+   deployPath: mongo_data_adapter/5/installing/linux_ppc64le/mongo_sles_12.mdx
+   ```
+
+   This is best defined within the product template heirarchy, where context variables can be used:
+
+   ```
+   {% block frontmatter %}
+   deployPath: mongo_data_adapter/{{ product.version }}/installing/linux_{{platform.arch}}/mongo_{{deploy.map_platform[platform.name]}}.mdx
+   {% endblock frontmatter %}
+   ```
+
+The 2nd technique above lends itself well to writing redirect rules that prevent broken links when deployment paths change:
+
+```
+{% block frontmatter %}
+redirects:
+  - mongo_data_adapter/{{ product.version }}/04_installing_the_mongo_data_adapter/{{deploy.expand_arch[platform.arch]}}/mongo_{{deploy.map_platform_old[platform.name]}}_{{platform.arch | replace("_64", "")}}.mdx
+{% endblock frontmatter %}
+```
+
+**Note:** the path generated from that pattern wouldn't normally be a valid redirect rule - it should start with `/` and *not* end with `.mdx`. For convenience, the deploy script will automatically rewrite redirects written in this form to the proper format, thus allowing you to just copy the old `deployPath` value to a redirect before modifying it. 

install_template/deploy.mjs

@@ -72,6 +72,8 @@ const moveDoc = async (product, platform, version) => {
       context.platform.arch,
     ].join("_") + ".mdx";
 
+  const srcFilepath = path.resolve(__dirname, "renders", srcFilename);
+
   const prefix = {
     rhel_8_x86_64: "01",
     other_linux8_x86_64: "02",
@@ -145,8 +147,10 @@ const moveDoc = async (product, platform, version) => {
   const fmtArchPath = (ctx) => expand_arch[ctx.platform.arch];
   const fmtArchFilename = (ctx) => ctx.platform.arch.replace(/_?64/g, "");
 
+  const [srcContent, integralDeploymentPath] = await readSource(srcFilepath);
+
   // prettier-ignore
-  const destFilename = match(context, 
+  const destFilename = integralDeploymentPath || match(context, 
     when({product: {name: "EDB*Plus", version: 40}, platform: {name: "SLES 12"}}, 
       (ctx) => `edb_plus/40/03_installing_edb_plus/install_on_linux/${fmtArchPath(ctx)}/edbplus_sles12_${fmtArchFilename(ctx)}.mdx`),
     when({product: {name: "EDB*Plus", version: 40}, platform: {name: "SLES 15"}}, 
@@ -168,7 +172,7 @@ const moveDoc = async (product, platform, version) => {
     when({product: {name: "EDB*Plus", version: 40}, platform: {name: "RHEL 8"}}, 
       (ctx) => `edb_plus/40/03_installing_edb_plus/install_on_linux/${fmtArchPath(ctx)}/edbplus_rhel8_${fmtArchFilename(ctx)}.mdx`),
     when({product: {name: "EDB*Plus", version: 40}, platform: {name: "RHEL 8 or OL 8"}}, 
-      (ctx) => `edb_plus/40/03_installing_edb_plus/install_on_linux/${fmtArchPath(ctx)}/edbplus_RHEL8_${fmtArchFilename(ctx)}.mdx`),
+      (ctx) => `edb_plus/40/03_installing_edb_plus/install_on_linux/${fmtArchPath(ctx)}/edbplus_rhel8_${fmtArchFilename(ctx)}.mdx`),
 
 
     when({product: {name: "EDB Postgres Advanced Server", version: 14}, platform: {name: "CentOS 7"}}, 
@@ -288,30 +292,7 @@ const moveDoc = async (product, platform, version) => {
       (ctx) => `efm/4/03_installing_efm/${fmtArchPath(ctx)}/efm4_ubuntu18_${fmtArchFilename(ctx)}.mdx`),      
     when({product: {name: "Failover Manager", version: 4}, platform: {name: "Ubuntu 20.04"}}, 
       (ctx) => `efm/4/03_installing_efm/${fmtArchPath(ctx)}/efm4_ubuntu20_${fmtArchFilename(ctx)}.mdx`),      
-
-    when({product: {name: "Hadoop Foreign Data Wrapper", version: 2}, platform: {name: "SLES 12"}}, 
-      (ctx) => `hadoop_data_adapter/2/05_installing_the_hadoop_data_adapter/${fmtArchPath(ctx)}/hadoop_sles12_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "Hadoop Foreign Data Wrapper", version: 2}, platform: {name: "SLES 15"}}, 
-      (ctx) => `hadoop_data_adapter/2/05_installing_the_hadoop_data_adapter/${fmtArchPath(ctx)}/hadoop_sles15_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "Hadoop Foreign Data Wrapper", version: 2}, platform: {name: "Ubuntu 20.04"}}, 
-      (ctx) => `hadoop_data_adapter/2/05_installing_the_hadoop_data_adapter/${fmtArchPath(ctx)}/hadoop_ubuntu20_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "Hadoop Foreign Data Wrapper", version: 2}, platform: {name: "Ubuntu 18.04"}}, 
-      (ctx) => `hadoop_data_adapter/2/05_installing_the_hadoop_data_adapter/${fmtArchPath(ctx)}/hadoop_ubuntu18_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "Hadoop Foreign Data Wrapper", version: 2}, platform: {name: "Debian 11"}}, 
-      (ctx) => `hadoop_data_adapter/2/05_installing_the_hadoop_data_adapter/${fmtArchPath(ctx)}/hadoop_deb11_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "Hadoop Foreign Data Wrapper", version: 2}, platform: {name: "Debian 10"}}, 
-      (ctx) => `hadoop_data_adapter/2/05_installing_the_hadoop_data_adapter/${fmtArchPath(ctx)}/hadoop_deb10_${fmtArchFilename(ctx)}.mdx`),
-      when({product: {name: "Hadoop Foreign Data Wrapper", version: 2}, platform: {name: "CentOS 7"}}, 
-      (ctx) => `hadoop_data_adapter/2/05_installing_the_hadoop_data_adapter/${fmtArchPath(ctx)}/hadoop_centos7_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "Hadoop Foreign Data Wrapper", version: 2}, platform: {name: "AlmaLinux 8 or Rocky Linux 8"}}, 
-      (ctx) => `hadoop_data_adapter/2/05_installing_the_hadoop_data_adapter/${fmtArchPath(ctx)}/hadoop_other_linux8_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "Hadoop Foreign Data Wrapper", version: 2}, platform: {name: "RHEL 7 or OL 7"}}, 
-      (ctx) => `hadoop_data_adapter/2/05_installing_the_hadoop_data_adapter/${fmtArchPath(ctx)}/hadoop_rhel7_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "Hadoop Foreign Data Wrapper", version: 2}, platform: {name: "RHEL 8 or OL 8"}}, 
-      (ctx) => `hadoop_data_adapter/2/05_installing_the_hadoop_data_adapter/${fmtArchPath(ctx)}/hadoop_rhel8_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "Hadoop Foreign Data Wrapper", version: 2}, platform: {name: "RHEL 8"}}, 
-      (ctx) => `hadoop_data_adapter/2/05_installing_the_hadoop_data_adapter/${fmtArchPath(ctx)}/hadoop_rhel8_${fmtArchFilename(ctx)}.mdx`),
-
+
     when({product: {name: "EDB JDBC Connector"}, platform: {name: "CentOS 7"}}, 
       (ctx) => `jdbc_connector/42.5.0.1/04_installing_and_configuring_the_jdbc_connector/01_installing_the_connector_with_an_rpm_package/${fmtArchPath(ctx)}/jdbc42_centos7_${fmtArchFilename(ctx)}.mdx`),
     when({product: {name: "EDB JDBC Connector"}, platform: {name: "AlmaLinux 8 or Rocky Linux 8"}}, 
@@ -357,53 +338,6 @@ const moveDoc = async (product, platform, version) => {
       (ctx) => `migration_toolkit/55/05_installing_mtk/install_on_linux/${fmtArchPath(ctx)}/mtk55_centos7_${fmtArchFilename(ctx)}.mdx`),
     when({product: {name: "Migration Toolkit"}, platform: {name: "RHEL 8"}}, 
       (ctx) => `migration_toolkit/55/05_installing_mtk/install_on_linux/${fmtArchPath(ctx)}/mtk55_rhel8_${fmtArchFilename(ctx)}.mdx`),
-
-    when({product: {name: "MongoDB Foreign Data Wrapper", version: 5}, platform: {name: "SLES 12"}}, 
-      (ctx) => `mongo_data_adapter/5/04_installing_the_mongo_data_adapter/${fmtArchPath(ctx)}/mongo_sles12_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "MongoDB Foreign Data Wrapper", version: 5}, platform: {name: "SLES 15"}}, 
-      (ctx) => `mongo_data_adapter/5/04_installing_the_mongo_data_adapter/${fmtArchPath(ctx)}/mongo_sles15_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "MongoDB Foreign Data Wrapper", version: 5}, platform: {name: "Ubuntu 20.04"}}, 
-      (ctx) => `mongo_data_adapter/5/04_installing_the_mongo_data_adapter/${fmtArchPath(ctx)}/mongo_ubuntu20_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "MongoDB Foreign Data Wrapper", version: 5}, platform: {name: "Ubuntu 18.04"}}, 
-      (ctx) => `mongo_data_adapter/5/04_installing_the_mongo_data_adapter/${fmtArchPath(ctx)}/mongo_ubuntu18_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "MongoDB Foreign Data Wrapper", version: 5}, platform: {name: "Debian 11"}}, 
-      (ctx) => `mongo_data_adapter/5/04_installing_the_mongo_data_adapter/${fmtArchPath(ctx)}/mongo_deb11_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "MongoDB Foreign Data Wrapper", version: 5}, platform: {name: "Debian 10"}}, 
-      (ctx) => `mongo_data_adapter/5/04_installing_the_mongo_data_adapter/${fmtArchPath(ctx)}/mongo_deb10_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "MongoDB Foreign Data Wrapper", version: 5}, platform: {name: "CentOS 7"}}, 
-      (ctx) => `mongo_data_adapter/5/04_installing_the_mongo_data_adapter/${fmtArchPath(ctx)}/mongo_centos7_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "MongoDB Foreign Data Wrapper", version: 5}, platform: {name: "AlmaLinux 8 or Rocky Linux 8"}}, 
-      (ctx) => `mongo_data_adapter/5/04_installing_the_mongo_data_adapter/${fmtArchPath(ctx)}/mongo_other_linux8_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "MongoDB Foreign Data Wrapper", version: 5}, platform: {name: "RHEL 7 or OL 7"}}, 
-      (ctx) => `mongo_data_adapter/5/04_installing_the_mongo_data_adapter/${fmtArchPath(ctx)}/mongo_rhel7_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "MongoDB Foreign Data Wrapper", version: 5}, platform: {name: "RHEL 8 or OL 8"}}, 
-      (ctx) => `mongo_data_adapter/5/04_installing_the_mongo_data_adapter/${fmtArchPath(ctx)}/mongo_rhel8_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "MongoDB Foreign Data Wrapper", version: 5}, platform: {name: "RHEL 8"}}, 
-      (ctx) => `mongo_data_adapter/5/04_installing_the_mongo_data_adapter/${fmtArchPath(ctx)}/mongo_rhel8_${fmtArchFilename(ctx)}.mdx`),
-
-    when({product: {name: "MySQL Foreign Data Wrapper", version: 2}, platform: {name: "RHEL 8 or OL 8"}}, 
-      (ctx) => `mysql_data_adapter/2/04_installing_the_mysql_data_adapter/${fmtArchPath(ctx)}/mysql_rhel8_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "MySQL Foreign Data Wrapper", version: 2}, platform: {name: "AlmaLinux 8 or Rocky Linux 8"}}, 
-      (ctx) => `mysql_data_adapter/2/04_installing_the_mysql_data_adapter/${fmtArchPath(ctx)}/mysql_other_linux8_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "MySQL Foreign Data Wrapper", version: 2}, platform: {name: "RHEL 7 or OL 7"}}, 
-      (ctx) => `mysql_data_adapter/2/04_installing_the_mysql_data_adapter/${fmtArchPath(ctx)}/mysql_rhel7_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "MySQL Foreign Data Wrapper", version: 2}, platform: {name: "CentOS 7"}}, 
-      (ctx) => `mysql_data_adapter/2/04_installing_the_mysql_data_adapter/${fmtArchPath(ctx)}/mysql_centos7_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "MySQL Foreign Data Wrapper", version: 2}, platform: {name: "RHEL 8"}}, 
-      (ctx) => `mysql_data_adapter/2/04_installing_the_mysql_data_adapter/${fmtArchPath(ctx)}/mysql_rhel8_${fmtArchFilename(ctx)}.mdx`),
-
-    when({product: {name: "MySQL Foreign Data Wrapper", version: 2}, platform: {name: "SLES 12"}}, 
-      (ctx) => `mysql_data_adapter/2/04_installing_the_mysql_data_adapter/${fmtArchPath(ctx)}/mysql_sles12_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "MySQL Foreign Data Wrapper", version: 2}, platform: {name: "SLES 15"}}, 
-      (ctx) => `mysql_data_adapter/2/04_installing_the_mysql_data_adapter/${fmtArchPath(ctx)}/mysql_sles15_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "MySQL Foreign Data Wrapper", version: 2}, platform: {name: "Debian 10"}}, 
-      (ctx) => `mysql_data_adapter/2/04_installing_the_mysql_data_adapter/${fmtArchPath(ctx)}/mysql_deb10_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "MySQL Foreign Data Wrapper", version: 2}, platform: {name: "Debian 11"}}, 
-      (ctx) => `mysql_data_adapter/2/04_installing_the_mysql_data_adapter/${fmtArchPath(ctx)}/mysql_deb11_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "MySQL Foreign Data Wrapper", version: 2}, platform: {name: "Ubuntu 18.04"}}, 
-      (ctx) => `mysql_data_adapter/2/04_installing_the_mysql_data_adapter/${fmtArchPath(ctx)}/mysql_ubuntu18_${fmtArchFilename(ctx)}.mdx`),
-    when({product: {name: "MySQL Foreign Data Wrapper", version: 2}, platform: {name: "Ubuntu 20.04"}}, 
-      (ctx) => `mysql_data_adapter/2/04_installing_the_mysql_data_adapter/${fmtArchPath(ctx)}/mysql_ubuntu20_${fmtArchFilename(ctx)}.mdx`),
 
     when({product: {name: "EDB OCL Connector"}, platform: {name: "SLES 12"}}, 
       (ctx) => `ocl_connector/${ctx.product.version}/04_open_client_library/01_installing_and_configuring_the_ocl_connector/install_on_linux_using_edb_repo/${fmtArchPath(ctx)}/ocl_connector14_sles12_${fmtArchFilename(ctx)}.mdx`),
@@ -630,18 +564,17 @@ const moveDoc = async (product, platform, version) => {
     return { note: `Skipping (no mapping): ${srcFilename}`, context };
   }
 
-  const src = path.resolve(__dirname, "renders", srcFilename);
-  const dest = path.resolve(__dirname, destPath, destFilename);
+  const destFilepath = path.resolve(__dirname, destPath, destFilename);
   try {
-    await fs.mkdir(path.dirname(dest), { recursive: true });
-    await fs.copyFile(src, dest);
-    return { success: `deployed ${src} to ${dest}` };
+    await fs.mkdir(path.dirname(destFilepath), { recursive: true });
+    await fs.writeFile(destFilepath, srcContent, "utf8");
+    return { success: `deployed ${srcFilepath} to ${destFilepath}` };
   } catch (err) {
     return {
       warn: err.toString(),
       context: {
-        src,
-        dest,
+        srcFilepath,
+        destFilepath,
       },
     };
   }
@@ -688,4 +621,55 @@ const generateContext = (product, platform, version) => {
   };
 };
 
+/**
+ * Reads the source mdx file, parse out the deployment path and filename from the MDX frontmatter
+ * @param srcPath the path + name of the mdx file to read
+ * @returns [full contents, the relative deployment path], undefined on error
+ */
+const readSource = async (srcPath) => {
+  const frontmatterRE = /^(?<open>---\s*?\n)(?<yaml>.+?\n)(?<close>---\s*?\n)/s;
+
+  try {
+    let src = await fs.readFile(srcPath, "utf8");
+    const frontmatter = yaml.parseDocument(
+      src.match(frontmatterRE)?.groups?.yaml,
+    );
+
+    const deployPath = frontmatter.contents.get("deployPath");
+    const redirects = frontmatter.contents.get("redirects");
+
+    // delete deployPath but preserve any comments that might've been attached
+    if (deployPath) {
+      let deployComments = "";
+      for (let { key, value } of frontmatter.contents.items) {
+        if (
+          (key.value || key) === "deployPath" &&
+          (key.commentBefore || value.commentBefore)
+        ) {
+          deployComments =
+            (key.commentBefore || "") + (value.commentBefore || "");
+        }
+        if (key.value === "redirects")
+          key.commentBefore = deployComments + (key.commentBefore || "");
+      }
+      frontmatter.contents.delete("deployPath");
+    }
+
+    for (let i = 0; i < redirects?.items?.length; ++i) {
+      redirects.items[i].value = redirects.items[i].value
+        .replace(/^\/?/, "/")
+        .replace(/\.mdx$/, "");
+    }
+
+    src = src.replace(
+      frontmatterRE,
+      (_, open, fmYaml, close) => open + frontmatter.toString() + close,
+    );
+
+    return [src, deployPath];
+  } catch (e) {
+    console.log(srcPath, e);
+  }
+};
+
 run();

install_template/package.json

@@ -13,6 +13,6 @@
     "lodash.ismatch": "^4.4.0",
     "nunjucks": "^3.2.3",
     "prettier": "^2.4.0",
-    "yaml": "^1.10.2"
+    "yaml": "^2.1.3"
   }
 }

install_template/templates/platformBase/_deploymentConstants.njk

@@ -0,0 +1,37 @@
+{% set expand_arch = {
+    ppcle: "ibm_power_ppc64le",
+    x86: "x86_amd64",
+    x86_64: "x86_amd64",
+    ppc64le: "ibm_power_ppc64le"
+  } 
+%}
+{% set map_platform_old = {
+    "Debian 10": "deb10",
+    "Debian 11": "deb11",
+    "Ubuntu 18.04": "ubuntu18",
+    "Ubuntu 20.04": "ubuntu20",
+    "Ubuntu 22.04": "ubuntu22",
+    "SLES 12": "sles12",
+    "SLES 15": "sles15",
+    "CentOS 7": "centos7",
+    "AlmaLinux 8 or Rocky Linux 8": "other_linux8",
+    "RHEL 7 or OL 7": "rhel7",
+    "RHEL 8 or OL 8": "rhel8",
+    "RHEL 8": "rhel8"
+  }
+%}
+{% set map_platform = {
+    "Debian 10": "debian_10",
+    "Debian 11": "debian_11",
+    "Ubuntu 18.04": "ubuntu_18",
+    "Ubuntu 20.04": "ubuntu_20",
+    "Ubuntu 22.04": "ubuntu_22",
+    "SLES 12": "sles_12",
+    "SLES 15": "sles_15",
+    "CentOS 7": "centos_7",
+    "AlmaLinux 8 or Rocky Linux 8": "other_linux_8",
+    "RHEL 7 or OL 7": "rhel_7",
+    "RHEL 8 or OL 8": "rhel_8",
+    "RHEL 8": "rhel_8"
+  }
+%}

install_template/templates/platformBase/base.njk

@@ -4,6 +4,7 @@ title: Installing {{ product.name }} on {{ platform.name }} {{ platform.arch }}
 # This topic is generated from templates. If you have feedback on it, instead of 
 # editing the page and creating a pull request, please enter a GitHub issue and 
 # the documentation team will update the templates accordingly.
+{% block frontmatter %}{% endblock frontmatter %}
 ---
 
   {% block pemslesnote %}{% endblock pemslesnote %}