From 65441b8e671c63d10c6e5235b3abccef1e36c4f5 Mon Sep 17 00:00:00 2001
From: Eric Forte <119343520+eric-forte-elastic@users.noreply.github.com>
Date: Tue, 7 May 2024 13:50:40 -0400
Subject: [PATCH] [FR] Update readme with wsl instructions for py312 (#3649)

* Update README

* Removed DaC Specifics

* Add troubleshooting guide.

* Update Troubleshooting.md

Co-authored-by: Mika Ayenson <Mikaayenson@users.noreply.github.com>

---------

Co-authored-by: Mika Ayenson <Mikaayenson@users.noreply.github.com>
---
 README.md          |  3 +++
 Troubleshooting.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+)
 create mode 100644 Troubleshooting.md

diff --git a/README.md b/README.md
index 76418901e..ac0fdbac7 100644
--- a/README.md
+++ b/README.md
@@ -89,6 +89,9 @@ pip3 install git+https://github.com/elastic/detection-rules.git#subdirectory=kql
 pip3 install lib/kibana lib/kql
 ```
 
+Remember, make sure to activate your virtual environment if you are using one. If installed via `make`, the associated virtual environment is created in `env/detection-rules-build/`.
+If you are having trouble using a Python 3.12 environment, please see the relevant section in our [troubleshooting guide](./Troubleshooting.md).
+
 To confirm that everything was properly installed, run with the `--help` flag
 ```console
 $  python -m detection_rules --help
diff --git a/Troubleshooting.md b/Troubleshooting.md
new file mode 100644
index 000000000..970cbc6b8
--- /dev/null
+++ b/Troubleshooting.md
@@ -0,0 +1,54 @@
+## Troubleshooting Python 3.12 Virtual Environment Installation and Activation
+
+When installing and managing virtual environments in Ubuntu (and other Linux operating systems), it is important to remember that the OS may require a specific version of python to perform operating system functions. For detection-rules we use Python version 3.12 which has a number of differences between older versions of Python, most notably no longer including `distutils` which can cause some unusual error messages. 
+
+This section of the guide offers some solutions to some common problems that can occur if one inadvertently overwrites the system's Python 3 installation with Python version 3.12. 
+
+### Issue: Python 3.12 system-wide installation replaced distutils links
+
+If you installed Python 3.12 as a system-wide (or at least WSL wide) installation, it would have replaced the links to distutils from 3.10 with 3.12. However, since Python 3.12 no longer includes distutils as a core package, this will cause issues. 
+
+Try installing python3.12-distutils using apt:
+
+```bash
+sudo apt install python3.12-distutils
+```
+
+If this command throws an error, you may need to fix apt first.
+
+### Issue: apt's python3 management
+
+If you're having issues with apt's python3 management, it might be due to a faulty python3-apt installation. Try reinstalling python3-apt with the following commands:
+
+```bash
+sudo apt remove --purge python3-apt
+sudo apt autoclean
+sudo apt install python3-apt
+```
+
+### Issue: Ubuntu needs to install python3.12-venv via apt
+
+On Ubuntu, you need to install python3.12-venv via apt:
+
+```bash
+sudo apt install python3.12-venv
+```
+
+
+### Issue: Python 3.12 removed get-pip.py
+
+Python 3.12 removed get-pip.py, but you can install pip using curl. If you don't have curl installed, you can install it using `sudo apt install curl`. Then, run the following commands:
+
+```bash
+curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
+sudo python3.12 get-pip.py
+```
+
+### Issue: ensurepip not installed
+
+If ensurepip is not installed, you can install it via pip:
+
+```bash
+python3.12 -m pip install ensurepip
+```
+