From 0f64d42eaad1aec67eb79f531a9ad10a72ec44ca Mon Sep 17 00:00:00 2001
From: Sandino Scheidegger <sandino@socialincome.org>
Date: Thu, 16 Nov 2023 12:48:59 +0100
Subject: [PATCH] refactor(general): update readme (#633)

---
 README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 44 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index d712fb0e8..65d61a551 100644
--- a/README.md
+++ b/README.md
@@ -81,11 +81,7 @@ Before you can start developing, you need to install the dependencies by
 running. Make sure you are using Node.js 18. If you are using Homebrew,
 you can install it with `brew install node@18` and follow
 [this](https://ralphjsmit.com/switch-between-nodejs-versions-homebrew)
-guide to switch between different versions of Node.js if need be. On
-MacBook Pro (Intel) there seems to be an issue if you don't use exactly
-the 18.15.0 Version:
-[Download](https://nodejs.org/dist/v18.15.0/node-v18.15.0.pkg) /
-[Issue](https://github.com/firebase/firebase-tools/issues/5614)
+guide to switch between different versions of Node.js if need be.
 
 ```shell
 npm install
@@ -94,9 +90,49 @@ npm install
 Once the dependencies are installed, you can start the different
 environments:
 
-- First, start the Firebase emulator with `npm run firebase:serve` —
-  console dashboard is available at
-  [localhost:4000](http://localhost:4000).
+### Step 1
+
+Start the Firebase emulator with `npm run firebase:serve` — console
+dashboard is available at [localhost:4000](http://localhost:4000).
+
+<details>
+<summary><strong>Troubleshooting Errors</strong></summary>
+
+#### macOS Error Handling
+
+### Issue 1:
+
+> Error: Could not start Pub/Sub Emulator, port taken.
+
+**Solution:**
+
+1. Identify the Process Using Port 8085:
+
+```
+lsof -i -P -n | grep java
+```
+
+2. Terminate the Conflicting Process:
+
+```
+kill [PID]
+```
+
+### Issue 2
+
+> Error: Fatal error occurred.
+
+On MacBook Pro (Intel) there seems to be an issue if you don't use
+exactly Node.js version 18.15.0
+([Issue](https://github.com/firebase/firebase-tools/issues/5614)).
+
+**Solution:**
+[Download 18.15.02](https://nodejs.org/dist/v18.15.0/node-v18.15.0.pkg)
+
+</details>
+
+### Step 2
+
 - To start the Admin Tool, run `npm run admin:serve` and open
   [localhost:3000](http://localhost:3000).
 - To start the Website, run `npm run website:serve` and open