Merge pull request #130 from vishnoianil/tshoot-help

Add troubleshooting help doc to capture known issues
instructlab · Apr 3, 2024 · df42839 · df42839
2 parents 9229045 + 03e2c58
commit df42839
Show file tree

Hide file tree

Showing 2 changed files with 29 additions and 0 deletions.
diff --git a/docs/dev-env.md b/docs/dev-env.md
@@ -64,3 +64,5 @@ This will check if the config.yaml exist and if it is a valid yaml file it will
 ## Workers
 
 By default, the podman compose stack includes a single worker running in test mode. In this mode, it will not actually perform the work of the jobs. It will pretend it did and immediately post results to the results queue.
+
+Please refer to the [troubleshooting guide](troubleshooting.md) if you encounter any issues. It lists some of the issues that we encountered while setting up the development environment and how we resolved them, so it might be helpful to you as well.
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -0,0 +1,27 @@
+# Troubleshooting Help
+
+## MacOs Dev Environment
+
+- `make run-dev` throws following error
+
+        ```text
+        error getting credentials - err: exec: "docker-credential-osxkeychain": executable file not found in $PATH, out: ``
+        ```
+
+        If your dev machine has docker-compose installed, Podman compose will by default uses docker-compose to run the services. The error is because the docker-compose is not able to find the docker credential helper. To fix this, you need to install the docker credential helper.
+
+        ```bash
+        brew install docker-credential-helper
+        ```
+
+- `make run-dev` throws following error
+
+        ```text
+        ✘ bot Error         {"message":"unable to retrieve auth token: invalid username/password: unauthorized"}                                                                                                                                                                  1.1s
+        ✘ worker-test Error {"message":"unable to retrieve auth token: invalid username/password: unauthorized"}                                                                                                                                                                  1.1s
+        ✘ redis Error       context canceled                                                                                                                                                                                                                                      9.3s
+        Error response from daemon: {"message":"unable to retrieve auth token: invalid username/password: unauthorized"}
+        Error: executing /usr/local/bin/docker-compose up: exit status 18
+        ```
+
+        Make sure podman desktop is configured with ghcr.io registry. To check this, open the podman desktop dashboard, and go to Settings -> Registries. Select the Github Container Registry and make sure the credentials are set. You will have to use the Personal Access Token to authenticate with the Github Container Registry. Once Github Container Registry is configured, try running `make run-dev` again.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -64,3 +64,5 @@ This will check if the config.yaml exist and if it is a valid yaml file it will
		## Workers

		By default, the podman compose stack includes a single worker running in test mode. In this mode, it will not actually perform the work of the jobs. It will pretend it did and immediately post results to the results queue.

		Please refer to the [troubleshooting guide](troubleshooting.md) if you encounter any issues. It lists some of the issues that we encountered while setting up the development environment and how we resolved them, so it might be helpful to you as well.