Unverified Commit 3509e33c authored by Thomas Bouffard's avatar Thomas Bouffard Committed by GitHub
Browse files

test: allow to test netlify redirects (#258)


Co-authored-by: default avatarAdrien <adrien.lachambre@bonitasoft.com>
parent f387b29e
......@@ -17,15 +17,13 @@ endif::[]
image::https://api.netlify.com/api/v1/badges/df65c069-bb52-46d2-8bf0-8e16b6b21482/deploy-status[alt=Netlify Status,link=https://app.netlify.com/sites/documentation-bonita/deploys]
*_DISCLAIMER: this is a work in progress._*
This repository let you generate the Bonita documentation site. It uses {url-antora}[Antora] which processes {url-asciidoc}:[AsciiDoc]
This repository lets you generate the Bonita documentation site. It uses {url-antora}[Antora] which processes {url-asciidoc}:[AsciiDoc]
documentation content stored in various Git repositories.
== Documentation
See the xref:./docs/README[dedicated folder] for
See the xref:docs/README.adoc[dedicated folder] for
* documentation content contribution tips/guidelines
* architecture
......@@ -70,7 +68,7 @@ This includes building the documentation using:
* already checkout local documentation content repositories
* single branch for all components
* single branch of a single component
* a set of branches of various components. This is let validate https://docs.antora.org/antora/2.3/page/version-and-component-xrefs/[references between pages that belong to different docs components and/or versions]
* a set of branches of various components. This lets validate https://docs.antora.org/antora/2.3/page/version-and-component-xrefs/[references between pages that belong to different docs components and/or versions]
* ....
To know all available options, run
......@@ -189,9 +187,14 @@ For a faster loop, don't forget you can build the UI Bundle and the preview by c
----
==== http dev server
[NOTE]
====
Most of the time, pages can be browsed locally without requiring a http dev server. +
You may need it to test specific features like displaying Asciinema resources or testing redirects. See below for more details.
====
==== http server
Once the static site is build, you can run `npm run serve` and access it with `+http://localhost:8080+` to check if everything is working correctly (urls in taxonomy, links, ....).
......@@ -206,6 +209,15 @@ A http server is needed to correctly see the Asciinema resources (loading fail w
For instance, have a look at http://localhost:8080/bonita/2021.1/migrate-from-an-earlier-version-of-bonita-bpm#update-case-overview-pages
====
[TIP]
====
The http dev server is provided by the https://docs.netlify.com/cli/get-started/[Netlify CLI], so it is able to replicate a lot of the Netlify Edge features. +
In particular it is able to apply the same redirects as those used in production.
See for xref:docs/configure-netlify-redirects.adoc[configure Netlify redirects how-to] more details.
====
=== Production build
......
......@@ -16,7 +16,7 @@ function usage() {
echo "Options priority order for choosing the content of the preview when several options are provided:"
echo " - use-all-repositories"
echo " - single-branch-per-repo"
echo " - use-multi-repositorie"
echo " - use-multi-repositories"
echo "If no specific options: single branch per component"
echo ""
echo "Globals"
......@@ -43,7 +43,7 @@ function usage() {
echo "Environment configuration"
echo " --ci <boolean> 'false': assume the script is running on local dev machine and don't run some setup commands. Defaults to 'true'"
echo " --only-generate-playbook If this option is pass, only generate the preview Antora playbook and skip the documentation generation"
echo " --only-generate-playbook If set, only generate the preview Antora playbook and skip the documentation generation"
}
......
= Netlify redirects configuration
:icons: font
ifdef::env-github[]
:note-caption: :information_source:
:tip-caption: :bulb:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]
== Configuration files
......@@ -9,26 +17,26 @@ for more details about the how to configure the redirects.
== Testing the redirects
Currently, we manually test the redirects by deploying the `netlify.toml` file on a single page test site using the Netlify
dashboard. In this case, we only want to check the redirects, so we don't care to have real pages available. +
We don't update the redirects very often, so this is enough for our current usage.
Testing can be done locally thanks to the dev server provided by the https://docs.netlify.com/cli/get-started/[Netlify CLI].
It is able to use the `netlify.toml` used in production and the Netlify `_redirects` file that could be generated by Antora to manage alias. See https://github.com/bonitasoft/bonita-documentation-site/issues/177[#177].
More details about redirects handling in the https://cli.netlify.com/netlify-dev/#redirects[Netlify documentation].
See https://github.com/bonitasoft/bonita-documentation-site/issues/168[#168] for a more integrated solution.
=== Step by step procedure
- Connect to Netlify
- Open the _Bonita test redirect_ site
- From the _site overview_, click on the latest _production deploy_ (with the `published` tag)
- Download the zip of this deploy (using the small download arrow next to the deployment date).
- Open the zip and replace the content of the `netlify.toml` file with the new one (with the redirect you want to test).
- Re-zip, and go back to the _site overview_ view
- Upload the new zip (i.e the new site) using the drag and drop area (at the bottom of the _site overview_ view)
- When the deployment is done, click on it and click on _preview deploy_. It opens the site (with only one page), you can now test your redirect. For ex, if you want to test that _/bonita_ redirects to _/bonita/2021.2_ then add /bonita at the end of the url and check that the redirect is done.
- Build a preview with the components and versions needed for the test. See xref:../README.adoc#preview-support[README]
- Start the http dev server (see xref:../README.adoc#http-dev-server[README])
- In the console, you can see the redirects configuration currently used.
- Any changes in the Netlify redirects configuration is taken into account right away by the server, so the feedback loop is intended to be very short
[WARNING]
====
If your redirect returns `200`, the url won't be updated on the fake site if there is no page for the redirect. It returns 200 so you don't go to the 404 page. It is the case for the /latest redirect on the current configuration.
If your redirect returns `200`, the url won't be updated when you test the redirect.
It is the case for the /latest/* redirect, it redirects (for ex) on the 2021.2 documentation, but the url isn't updated. To validate it works you have to check the content of the page.
====
......
This diff is collapsed.
......@@ -5,15 +5,15 @@
"scripts": {
"clean": "rimraf build .cache",
"build": "antora --stacktrace --fetch --clean antora-playbook.yml",
"serve": "http-server build/site -c-1 --port 8080"
"serve": "netlify dev -d build/site --debug --port 8080"
},
"devDependencies": {
"@antora/cli": "^2.3.4",
"@antora/site-generator-default": "^2.3.4",
"fs-extra": "^9.0.1",
"http-server": "^0.12.3",
"js-yaml": "^4.0.0",
"minimist": "^1.2.5",
"netlify-cli": "^6.9.28",
"rimraf": "^3.0.2"
}
}
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment