Merge pull request #46 from f5devcentral/development

Add link checking for sites pages
f5devcentral · Oct 22, 2024 · f6191d6 · f6191d6
2 parents 4e994a1 + 45bd59d
commit f6191d6
Show file tree

Hide file tree

Showing 15 changed files with 137 additions and 25 deletions.
diff --git a/.github/workflows/build-pages.yml b/.github/workflows/build-pages.yml
@@ -0,0 +1,38 @@
+on:
+  push:
+  pull_request:
+    branches:
+      - main
+      - development
+  workflow_dispatch:
+
+name: Pages-CI
+
+jobs:
+  validate:
+    name: Validate HTML
+    strategy:
+      fail-fast: false
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          working-directory: ./pages
+          ruby-version: '3.3' # Not needed with a .ruby-version file
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+          cache-version: 0 # Increment this number if you need to re-download cached gems
+      - name: Cache HTMLProofer
+        id: cache-htmlproofer
+        uses: actions/cache@v3
+        with:
+          path: tmp/.htmlproofer
+          key: ${{ runner.os }}-htmlproofer
+      - name: Build Site
+        run: cd ./pages && bundle exec jekyll build
+      - name: Test with html-proofer
+        run: cd ./pages && bundle exec htmlproofer _site --ignore-urls "/github.com/,/web.archive.org/" --swap-urls '^/application-study-tool/:/'
+        env:
+          NOKOGIRI_USE_SYSTEM_LIBRARIES: true
diff --git a/README.md b/README.md
@@ -16,14 +16,14 @@ configuration, troubleshooting info, etc.
 The Application Study Tool is intended to provide enhanced insights into (classic) BIG-IP products, leveraging best in class
 open source telemetry tools. The full installation includes:
 
-* Custom Instance of OpenTelemetry Collector with enhanced BIG-IP data receivers (data fetched via iControlRest) [Full List of Metrics Collected](pages/receiver_metrics.md).
+* Custom Instance of OpenTelemetry Collector with enhanced BIG-IP data receivers (data fetched via iControlRest) [Full List of Metrics Collected](pages/components/otel_collector/receiver_metrics.md).
 * Prometheus timeseries database for storing and querying collected data.
 * Grafana Instance with pre-configured dashboards for quick insights at the device and "fleet" levels.
 
 The Application Study Tool has everything needed to quickly get up and running with application insights at less than
 production levels of reliability. For production/operational use cases, you can build on the included components,
 accounting for things like high availability, enhanced security via e.g. Grafana OIDC integration, and similar. Alternatively,
-the Openetlemetry Collector can be configured to send data to existing production ops monitoring tools as desired.
+the Opentelemetry Collector can be configured to send data to existing production ops monitoring tools as desired.
 
 ![](./pages/assets/ui.gif)
 
@@ -163,8 +163,8 @@ BIGIP_PASSWORD_2=bar-foo123!
 ```
 
 The variable name (the part on the left of the equal sign) must match the configured
-value for the devices that use this password in config/ast_defaults.yaml or device specifc
-cofig in config/bigip_receivers.yaml. In the following example, bigip/1 uses BIGIP_PASSWORD_1
+value for the devices that use this password in config/ast_defaults.yaml or device specific
+config in config/bigip_receivers.yaml. In the following example, bigip/1 uses BIGIP_PASSWORD_1
 from  the defaults and bigip/2 uses BIGIP_PASSWORD_2 from the device settings:
 
 ```
@@ -236,7 +236,7 @@ $ python /app/src/config_helper.py --generate-config
 This will write 2 new files in the services/otel_collector directory:
 
 * `receivers.yaml` - The final list of scraper configs and their settings.
-* `pipelines.yaml` - The final pipeline configs that map receievers to output destinations
+* `pipelines.yaml` - The final pipeline configs that map receivers to output destinations
 (prometheus, and optionally F5).
 
 ## Adding New Devices or Updating Configs
@@ -330,6 +330,20 @@ The default Grafana user/pass is `admin/admin`, and can be accessed at
 `http://<hostname>:3000`.
 
 
+## Updating AST Versions
+Updating to a new release of the AST repo can be done with the following general process:
+
+1. Review the release notes for all intermediate versions and check for warnings about
+special instructions / breaking changes.
+2. Backup your ast_defaults.yaml and bigip_receivers.yaml files.
+3. Stash changes, update the repo state, and unstash changes as follows:
+```shell
+git stash
+git pull origin main
+git checkout tags/RELEASE_VERSION #(e.g. tags/v0.7.0)
+git stash pop
+```
+
 ## Support
 
 For support, please open a GitHub issue.  Note, the code in this repository is community supported and is not supported by F5 Networks.  For a complete list of supported projects please reference [SUPPORT.md](SUPPORT.md).

diff --git a/pages/Gemfile b/pages/Gemfile
@@ -34,4 +34,6 @@ gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby]
 
 gem 'nokogiri'
 gem 'rack', '~> 2.2.4'
-gem 'rspec'
+gem 'rspec'
+
+gem "html-proofer", "~> 5.0", :group => :development
diff --git a/pages/Gemfile.lock b/pages/Gemfile.lock
@@ -1,28 +1,55 @@
 GEM
   remote: https://rubygems.org/
   specs:
+    Ascii85 (1.1.1)
     addressable (2.8.7)
       public_suffix (>= 2.0.2, < 7.0)
+    afm (0.2.2)
+    async (2.17.0)
+      console (~> 1.26)
+      fiber-annotation
+      io-event (~> 1.6, >= 1.6.5)
     bigdecimal (3.1.8)
     colorator (1.1.0)
     concurrent-ruby (1.3.4)
+    console (1.27.0)
+      fiber-annotation
+      fiber-local (~> 1.1)
+      json
     diff-lcs (1.5.1)
     em-websocket (0.5.3)
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0)
+    ethon (0.16.0)
+      ffi (>= 1.15.0)
     eventmachine (1.2.7)
     ffi (1.17.0-arm64-darwin)
     ffi (1.17.0-x86_64-linux-gnu)
+    fiber-annotation (0.2.0)
+    fiber-local (1.1.0)
+      fiber-storage
+    fiber-storage (1.0.0)
     forwardable-extended (2.6.0)
     google-protobuf (4.28.1-arm64-darwin)
       bigdecimal
       rake (>= 13)
     google-protobuf (4.28.1-x86_64-linux)
       bigdecimal
       rake (>= 13)
+    hashery (2.1.2)
+    html-proofer (5.0.9)
+      addressable (~> 2.3)
+      async (~> 2.1)
+      nokogiri (~> 1.13)
+      pdf-reader (~> 2.11)
+      rainbow (~> 3.0)
+      typhoeus (~> 1.3)
+      yell (~> 2.0)
+      zeitwerk (~> 2.5)
     http_parser.rb (0.8.0)
     i18n (1.14.6)
       concurrent-ruby (~> 1.0)
+    io-event (1.7.3)
     jekyll (4.3.4)
       addressable (~> 2.4)
       colorator (~> 1.0)
@@ -47,6 +74,7 @@ GEM
       jekyll (>= 3.8, < 5.0)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
+    json (2.7.2)
     just-the-docs (0.10.0)
       jekyll (>= 3.8.5)
       jekyll-include-cache
@@ -67,9 +95,16 @@ GEM
       racc (~> 1.4)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
+    pdf-reader (2.12.0)
+      Ascii85 (~> 1.0)
+      afm (~> 0.2.1)
+      hashery (~> 2.0)
+      ruby-rc4
+      ttfunk
     public_suffix (6.0.1)
     racc (1.8.1)
     rack (2.2.10)
+    rainbow (3.1.1)
     rake (13.2.1)
     rb-fsevent (0.11.2)
     rb-inotify (0.11.1)
@@ -89,21 +124,29 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.1)
+    ruby-rc4 (0.1.5)
     safe_yaml (1.0.5)
     sass-embedded (1.78.0-arm64-darwin)
       google-protobuf (~> 4.27)
     sass-embedded (1.78.0-x86_64-linux-gnu)
       google-protobuf (~> 4.27)
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
+    ttfunk (1.8.0)
+      bigdecimal (~> 3.1)
+    typhoeus (1.4.1)
+      ethon (>= 0.9.0)
     unicode-display_width (2.6.0)
     webrick (1.8.1)
+    yell (2.2.2)
+    zeitwerk (2.7.1)
 
 PLATFORMS
   arm64-darwin
   x86_64-linux-gnu
 
 DEPENDENCIES
+  html-proofer (~> 5.0)
   http_parser.rb (~> 0.6.0)
   jekyll (~> 4.3.4)
   just-the-docs (= 0.10.0)

diff --git a/pages/components/otel_collector/receiver_readme.md b/pages/components/otel_collector/receiver_readme.md
@@ -95,4 +95,4 @@ TLS config is documented further under the [opentelemetry collector's configtls
 
 ## Metrics
 
-Details about the metrics produced by this receiver can be found in [/docs/receiver_metrics.md](/docs/receiver_metrics.md)
+Details about the metrics produced by this receiver can be found in [Receiver Metrics Info]({{ site.url }}{{ site.baseurl }}components/otel_collector/receiver_metrics.html)
diff --git a/pages/config/config.md b/pages/config/config.md
@@ -9,20 +9,20 @@ permalink: /config
 
 # AST Configuration Management Overview
 This configuration section applies to the AST Opentelemetry Collector. For Grafana, Prometheus or other
-components, see the corresponding documentation in [> Components]({{site.baseurl}}/components/)
+components, see the corresponding documentation in [> Components]({{ site.url }}{{ site.baseurl }}components)
 
 
 ## Config Management Options
 In the post v0.6.0 management scheme, users can choose from one of the below options to manage
 the AST Otel Collector configs:
 
 1. Using a python script to generate full Otel Collector Config files from a small set of default
-settings and per-device overrides (recommended for most users, and includes migration path from old big-ips.json configs). See [Configuration > Configuration Helper (Recommended)]({{site.baseurl}}/config/config_helper/) for details.
+settings and per-device overrides (recommended for most users, and includes migration path from old big-ips.json configs). See [Configuration > Configuration Helper (Recommended)]({{ site.url }}{{ site.baseurl }}config/config_helper) for details.
 
 2. Manual maintenance of the Otel Collector Config Receivers and Pipelines files (recommended for 
-advanced use cases or people with their own automation pipelines). See [Configuration > Manual Configuration > Receiver/Pipeline Config]({{site.baseurl}}/config/manual_config/receivers_pipelines.html) for details.
+advanced use cases or people with their own automation pipelines). See [Configuration > Manual Configuration > Receiver/Pipeline Config]({{ site.url }}{{ site.baseurl }}config/manual_config/receivers_pipelines.html) for details.
 
 3. Manual maintenance of the Otel Collector Config files in
-[/services/otel_collector/defaults](https://github.com/f5devcentral/application-study-tool/blob/main/services/otel_collector/defaults). See [Configuration > Manual Configuration > Std Otel Collector Config]({{site.baseurl}}/config/manual_config/default_otel.html/) for details.
+[/services/otel_collector/defaults](https://github.com/f5devcentral/application-study-tool/blob/main/services/otel_collector/defaults). See [Configuration > Manual Configuration > Std Otel Collector Config]({{ site.url }}{{ site.baseurl }}config/manual_config/default_otel.html) for details.
 
 
diff --git a/pages/config/config_helper/config_datafabric.md b/pages/config/config_helper/config_datafabric.md
@@ -45,4 +45,4 @@ SENSOR_ID="YOUR_ID"
 $ vi .env
 ```
 
-Finally, [Run The Configuration Helper]({{site.baseurl}}/config/config_helper/#run-the-configuration-helper) and restart the project containers.
+Finally, [Run The Configuration Helper]({{ site.url }}{{ site.baseurl }}config/config_helper#run-the-configuration-helper) and restart the project containers.
diff --git a/pages/config/config_helper/config_defaults.md b/pages/config/config_helper/config_defaults.md
@@ -15,14 +15,14 @@ The file [/config/ast_defaults.yaml](https://github.com/f5devcentral/application
 contains global configuration settings that can be used to reduce the amount of boilerplate configuration
 required for each BigIP device to be monitored.
 
-Settings for each device are configured as described in [Configuration >	Configuration Helper (Recommended) > Device Configuration]({{site.baseurl}}/config/config_helper/config_receivers.html)
+Settings for each device are configured as described in [Configuration >	Configuration Helper (Recommended) > Device Configuration]({{ site.url }}{{ site.baseurl }}config/config_helper/config_receivers.html)
 
 {: .important }
 The config helper script must run after any changes to the default or device specific configs,
 and the Otel container restarted before changes will take effect.
 
 The config file appears as follows. Syntax for the bigip_receiver_defaults settings follow the spec laid 
-out in the [BigIP Receiver Readme]({{site.baseurl}}/components/otel_collector/receiver_readme.html) file.
+out in the [BigIP Receiver Readme]({{ site.url }}{{ site.baseurl }}components/otel_collector/receiver_readme.html) file.
 
 Details for each section are provided below.
 

diff --git a/pages/config/config_helper/config_helper.md b/pages/config/config_helper/config_helper.md
@@ -10,7 +10,7 @@ permalink: /config/config_helper
 # Managing AST Collector Configs With Config Helper
 
 This configuration section applies to the AST Opentelemetry Collector. For Grafana, Prometheus or other
-components, see the corresponding documentation in [> Components]({{site.baseurl}}/components/)
+components, see the corresponding documentation in [> Components]({{ site.url }}{{ site.baseurl }}components)
 
 ## Background
 AST includes a helper python script that can be used to streamline the management of the Opentelemetry
@@ -28,12 +28,12 @@ and the otel container restarted before changes will take effect.
 The default settings file reduces the amount of boilerplate that must be configured for each BigIP device
 to be monitored.
 
-* [Configuration >	Configuration Helper (Recommended) > Default Configuration]({{site.baseurl}}/config/config_helper/config_defaults.html)
+* [Configuration >	Configuration Helper (Recommended) > Default Configuration]({{ site.url }}{{ site.baseurl }}config/config_helper/config_defaults.html)
 
 Settings without a logical default (e.g. url of the bigIP device) or wishing to override the default can
 be set as described in:
 
-* [Configuration >	Configuration Helper (Recommended) > Device Configuration]({{site.baseurl}}/config/config_helper/config_receivers.html)
+* [Configuration >	Configuration Helper (Recommended) > Device Configuration]({{ site.url }}{{ site.baseurl }}config/config_helper/config_receivers.html)
 
 ## Run The Configuration Helper
 The config helper script can be run via docker (or natively if the system has python installed)

diff --git a/pages/config/config_helper/config_receivers.md b/pages/config/config_helper/config_receivers.md
@@ -17,7 +17,7 @@ The config helper script must run after any changes to the default or device spe
 and the otel container restarted before changes will take effect.
 
 The settings in this file are merged with the defaults outlined
-in [Configuration >	Configuration Helper (Recommended) > Default Configuration]({{site.baseurl}}/config/config_helper/config_defaults.html), with the more specific settings in this file taking precedence.
+in [Configuration >	Configuration Helper (Recommended) > Default Configuration]({{ site.url }}{{ site.baseurl }}config/config_helper/config_defaults.html), with the more specific settings in this file taking precedence.
 
 The following constraints apply:
 * There must be a top level entry for each BigIP Device you wish to monitor.

diff --git a/pages/config/config_migration.md b/pages/config/config_migration.md
@@ -22,7 +22,7 @@ where users were unable to view and modify the files to tune parameters for thei
 In the new process, the raw otel configs are exposed in the /services/otel_collector directory where
 they can be managed manually, or through continued use of a refactored config_helper script.
 
-For additional detail on configuration management options in the post v0.6.0 scheme, please see [Config Management](https://github.com/f5devcentral/application-study-tool/blob/main/config_management.md)
+For additional detail on configuration management options in the post v0.6.0 scheme, please see [Config Management]({{ site.url }}{{ site.baseurl }}config)
 
 ## Migrating From pre v0.6.0 Configs
 There's a python script in /src/config_helper.py which will convert the original big-ips.json schema

diff --git a/pages/datafabric/configuration.md b/pages/datafabric/configuration.md
@@ -5,4 +5,4 @@ parent: F5 Datafabric
 nav_order: 1
 ---
 
-See [>Configuration > Configuration Helper (Recommended) > Configure Export To F5 Datafabric]({{site.baseurl}}/config/config_helper/config_datafabric.html)
+See [>Configuration > Configuration Helper (Recommended) > Configure Export To F5 Datafabric]({{ site.url }}{{ site.baseurl }}config/config_helper/config_datafabric.html)
diff --git a/pages/getting_started.md b/pages/getting_started.md
@@ -11,7 +11,7 @@ nav_order: 2
 ## Background
 This instructions in this file will get a new installation up and running in as little as a few minutes.
 For more detailed information on AST config management options, see the
-[Configuration Management Overview]({{site.baseurl}}/config/) and related sections.
+[Configuration Management Overview]({{ site.url }}{{ site.baseurl }}config) and related sections.
 
 ### Prerequisites
 
@@ -131,7 +131,7 @@ BIGIP_PASSWORD_2=bar-foo123!
 ```
 
 The variable name (the part on the left of the equal sign) must match the configured
-value for the devices that use this password in config/ast_defaults.yaml or device specifc
+value for the devices that use this password in config/ast_defaults.yaml or device specific
 cofig in config/bigip_receivers.yaml. In the following example, bigip/1 uses BIGIP_PASSWORD_1
 from  the defaults and bigip/2 uses BIGIP_PASSWORD_2 from the device settings:
 
@@ -173,7 +173,7 @@ docker run --rm -it -w /app -v ${PWD}:/app --entrypoint /app/src/bin/init_entryp
 This will write 2 new files in the services/otel_collector directory:
 
 * `receivers.yaml` - The final list of scraper configs and their settings.
-* `pipelines.yaml` - The final pipeline configs that map receievers to output destinations
+* `pipelines.yaml` - The final pipeline configs that map receivers to output destinations
 (prometheus).
 
 ### Configure CA File
@@ -229,3 +229,18 @@ docker compose up
 #### View The Dashboards
 The default Grafana user/pass is `admin/admin`, and can be accessed at
 `http://<hostname>:3000`.
+
+
+## Updating AST Versions
+Updating to a new release of the AST repo can be done with the following general process:
+
+1. Review the release notes for all intermediate versions and check for warnings about
+special instructions / breaking changes.
+2. Backup your ast_defaults.yaml and bigip_receivers.yaml files.
+3. Stash changes, update the repo state, and unstash changes as follows:
+```shell
+git stash
+git pull origin main
+git checkout tags/RELEASE_VERSION #(e.g. tags/v0.7.0)
+git stash pop
+```
diff --git a/pages/index.md b/pages/index.md
@@ -9,7 +9,7 @@ nav_order: 1
 The Application Study Tool is intended to provide enhanced insights into (classic) BIG-IP products, leveraging best in class
 open source telemetry tools. The full installation includes:
 
-* Custom Instance of OpenTelemetry Collector with enhanced BIG-IP data receivers (data fetched via iControlRest) [Receiver Metrics Info]({{site.baseurl}}/components/otel_collector/receiver_metrics.html).
+* Custom Instance of OpenTelemetry Collector with enhanced BIG-IP data receivers (data fetched via iControlRest) [Receiver Metrics Info]({{ site.url }}{{ site.baseurl }}components/otel_collector/receiver_metrics.html).
 * Prometheus timeseries database for storing and querying collected data.
 * Grafana Instance with pre-configured dashboards for quick insights at the device and "fleet" levels.
 

diff --git a/pages/troubleshooting/troubleshooting.md b/pages/troubleshooting/troubleshooting.md
@@ -138,4 +138,4 @@ the 'BigIP Collector Stats' dashboard at the top level of the Dashboards section
 ## GTM and DNS Metrics Not Loading
 
 Metrics for DNS and GTM are disabled by default. See 
-[Configuration > Configuration Helper (Recommended) > Configure DNS & GTM]({{site.baseurl}}/config/config_helper/config_dns_gtm.html) for instructions to enable.
+[Configuration > Configuration Helper (Recommended) > Configure DNS & GTM]({{ site.url }}{{ site.baseurl }}config/config_helper/config_dns_gtm.html) for instructions to enable.