From 2ff0cb4ea66bce2cdc40ce2f455457c94fa2d0a8 Mon Sep 17 00:00:00 2001
From: Keith Millette <keith@xx.network>
Date: Tue, 16 Jul 2024 13:01:20 +0900
Subject: [PATCH] Modify handbook to reflect support for Ubuntu Server LTS,
 versions 20.04, 22.04 and 24.04.

---
 website/docs/gateway/1-getting-started.md      |  4 ++--
 .../docs/gateway/2-software-dependencies.md    | 18 ++++++++++++++++++
 website/docs/node/1-getting-started.md         |  4 ++--
 website/docs/node/2-software-dependencies.md   | 18 ++++++++++++++++++
 website/docs/specifications.md                 | 13 ++++++++++++-
 5 files changed, 52 insertions(+), 5 deletions(-)

diff --git a/website/docs/gateway/1-getting-started.md b/website/docs/gateway/1-getting-started.md
index 9198b33..8731ff5 100644
--- a/website/docs/gateway/1-getting-started.md
+++ b/website/docs/gateway/1-getting-started.md
@@ -17,9 +17,9 @@ As a node runner you will need to know the following for use with this guide and
 
 ## The Operating System
 
-:::danger Have you installed Ubuntu Server 20.04 LTS on the gateway computer?
+:::danger Have you installed an OS other than Ubuntu Server 20.04 LTS, 22.04 LTS or 24.04 LTS on the gateway computer?
 :::
-The xx Network team may not be able to assist you if problems arise on OSs other than Ubuntu Server 20.04 LTS. Other versions of Ubuntu (Ex. 18.04, 22.10, etc.), flavors of Ubuntu (Ex. Ubuntu Desktop, Kubuntu, etc.), and Linux distributions (Ex. Arch, Fedora, etc.) have not been tested for compatibility with the xx Network software. That is not to say that the xx Network software can only be run on Ubutnu Server 20.04 LTS, but it may not be fully compatible due to the various versions of software that are installed by default by the OS maintainer. Refer to the [Install Ubuntu Server](https://ubuntu.com/tutorials/install-ubuntu-server#1-overview) documentation to install [Ubuntu Server 20.04 LTS](https://releases.ubuntu.com/20.04/) which Ubuntu has committed to provide hardware and maintenance updates until [April 2030](https://ubuntu.com/about/release-cycle).
+The xx Network team may not be able to assist you if problems arise on OSs other than those [tested and supported](../specifications.md). Other versions of Ubuntu (Ex. 18.04, 22.10, etc.), flavors of Ubuntu (Ex. Ubuntu Desktop, Kubuntu, etc.), and Linux distributions (Ex. Arch, Fedora, etc.) have not been tested for compatibility with the xx Network software. That is not to say that the xx Network software can only be run on the recommended OSs, but it may not be fully compatible due to the various versions of software that are installed by default by the OS maintainer.
 
 ## The *root* user
 
diff --git a/website/docs/gateway/2-software-dependencies.md b/website/docs/gateway/2-software-dependencies.md
index 3fe2308..e2350b2 100644
--- a/website/docs/gateway/2-software-dependencies.md
+++ b/website/docs/gateway/2-software-dependencies.md
@@ -46,6 +46,24 @@ sudo shutdown -r now
 
 ## Install cMixx dependent Python modules
 
+:::note
+
+If you are installing on **Ubuntu Server 24.04 LTS**, you will likely see the following message when installing the Python modules.
+
+<details>
+  <summary>`error: externally-managed-environment`.</summary>
+
+**This should only be required for Ubuntu Server 24.04 LTS.**
+
+To resolve this error, run the following commands:
+```
+sudo mv /usr/lib/python3.12/EXTERNALLY-MANAGED /usr/lib/python3.12/EXTERNALLY-MANAGED.bak
+```
+You should now be able to continue.
+</details>
+
+:::
+
 ```
 sudo pip3 install -U pip
 ```
diff --git a/website/docs/node/1-getting-started.md b/website/docs/node/1-getting-started.md
index ef07d42..3fb2e25 100644
--- a/website/docs/node/1-getting-started.md
+++ b/website/docs/node/1-getting-started.md
@@ -17,9 +17,9 @@ As a node runner you will need to know the following for use with this guide and
 
 ## The Operating System
 
-:::danger Have you installed Ubuntu Server 20.04 LTS on the node computer?
+:::danger Have you installed an OS other than Ubuntu Server 20.04 LTS, 22.04 LTS or 24.04 LTS on the node computer?
 :::
-The xx Network team may not be able to assist you if problems arise on OSs other than Ubuntu Server 20.04 LTS. Other versions of Ubuntu (Ex. 18.04, 22.10, etc.), flavors of Ubuntu (Ex. Ubuntu Desktop, Kubuntu, etc.), and Linux distributions (Ex. Arch, Fedora, etc.) have not been tested for compatibility with the xx Network software. That is not to say that the xx Network software can only be run on Ubutnu Server 20.04 LTS, but it may not be fully compatible due to the various versions of software that are installed by default by the OS maintainer. Refer to the [Install Ubuntu Server](https://ubuntu.com/tutorials/install-ubuntu-server#1-overview) documentation to install [Ubuntu Server 20.04 LTS](https://releases.ubuntu.com/20.04/) which Ubuntu has committed to provide hardware and maintenance updates until [April 2030](https://ubuntu.com/about/release-cycle).
+The xx Network team may not be able to assist you if problems arise on OSs other than those [tested and supported](../specifications.md). Other versions of Ubuntu (Ex. 18.04, 22.10, etc.), flavors of Ubuntu (Ex. Ubuntu Desktop, Kubuntu, etc.), and Linux distributions (Ex. Arch, Fedora, etc.) have not been tested for compatibility with the xx Network software. That is not to say that the xx Network software can only be run on the recommended OSs, but it may not be fully compatible due to the various versions of software that are installed by default by the OS maintainer.
 
 ## The *root* user
 
diff --git a/website/docs/node/2-software-dependencies.md b/website/docs/node/2-software-dependencies.md
index 38750d3..5624251 100644
--- a/website/docs/node/2-software-dependencies.md
+++ b/website/docs/node/2-software-dependencies.md
@@ -47,6 +47,24 @@ sudo shutdown -r now
 
 ## Install cMixx dependent Python modules
 
+:::note
+
+If you are installing on **Ubuntu Server 24.04 LTS**, you will likely see the following message when installing the Python modules.
+
+<details>
+  <summary>`error: externally-managed-environment`.</summary>
+
+**This should only be required for Ubuntu Server 24.04 LTS.**
+
+To resolve this error, run the following commands:
+```
+sudo mv /usr/lib/python3.12/EXTERNALLY-MANAGED /usr/lib/python3.12/EXTERNALLY-MANAGED.bak
+```
+You should now be able to continue.
+</details>
+
+:::
+
 ```
 sudo pip3 install -U pip
 ```
diff --git a/website/docs/specifications.md b/website/docs/specifications.md
index 3d09fc1..67d014d 100644
--- a/website/docs/specifications.md
+++ b/website/docs/specifications.md
@@ -4,7 +4,18 @@ sidebar_position: 2
 
 # Specifications
 
-Each xx Node is comprised of two computers, a NODE computer and a GATEWAY computer.
+## Operating System
+
+Each xx Node is comprised of two computers, a NODE computer and a GATEWAY computer. The xx network team has tested, supports and recommends, the following operating systems.
+
+### Tested and Supported
+ * Ubuntu Server 20.04 LTS
+ * Ubuntu Server 22.04 LTS
+ * Ubunti Server 24.04 LTS
+
+:::info
+This is not to say that the xx Network software can only be run on the recommended OSs, but it may not be fully compatible due to the various versions of software that are installed by default by the OS maintainer.
+:::
 
 ## Node Computer
 
-- 
GitLab