Merge branch 'main' of hf.co:spaces/caltech-animal-tracking/Primate_Batch_Detection

README.md

@@ -4,10 +4,149 @@ emoji: 💻
 colorFrom: purple
 colorTo: gray
 sdk: gradio
-sdk_version: 5.24.0
+sdk_version: 5.46.0
 app_file: app_batch.py
 pinned: false
 license: apache-2.0
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+
+# Primate Batch Detection: Installation & Troubleshooting Guide
+
+## Installation Guide
+
+### Prerequisites
+- Computer with GPU, this guide has been tested on an NVIDIA 4090 and 4060.
+- 20-50 min of time
+
+### General Tips 
+- Check the troubleshooting guide at the bottom of the page
+- If you have already set up WSL, Docker, or NVIDIA Container Toolkit before, feel free to skip those steps.
+- Use Google / ChatGPT to look up your errors
+- Reread the instructions carefully
+- Proceed forward anyways and see if it causes an issue
+- Anytime a terminal command with $VARIABLE_NAME or \<VARIABLE_NAME\>, it means that you should substitute in your appropriate variable or username, without the $ or < decorators.
+- Try opening and closing the terminal window you're in, or restart your computer.
+
+---
+
+### 1. Set Up WSL (Windows Users Only)
+
+If you're using Windows, you'll need to install the **Windows Subsystem for Linux (WSL)**:
+
+We recommend using **Ubuntu 22.04** as your Linux distribution.
+
+1. Open Powershell and install the WSL command: 
+
+  ```wsl --install Ubuntu```
+
+2. Set the default Linux distribution used with WSL:
+
+  ```wsl.exe --set-default Ubuntu```
+
+for more information visit: [WSL Installation Guide (Microsoft)](https://learn.microsoft.com/en-us/windows/wsl/install)
+
+Now open the WSL terminal through your Start menu.
+
+**Important:** Run all following commands in the **WSL terminal**, **not PowerShell**.
+
+---
+
+### 2. Install Docker (Mac and Linux Users Start Here)
+
+Follow these guides to install Docker in your WSL Ubuntu environment:
+
+1. Follow this guide using "Prerequisites" and "Install Docker Desktop":
+
+- [Install Docker Desktop](https://docs.docker.com/desktop/setup/install/linux/ubuntu/)
+
+2. Through the previous link, you should have followed step 1 of "Install using the apt repository" as part of your installation process.
+   Now complete steps 2-3 of that section as well:
+
+- [Install Docker Engine](https://docs.docker.com/engine/install/ubuntu/)
+
+---
+
+### 3. Install the NVIDIA Container Toolkit
+
+This is necessary for GPU support inside Docker containers:
+
+**Note:** Most likely, unless you built your own computer recently, you will already have installed NVIDIA drivers for your computer. Feel free to ignore the Prerequisites section.
+
+1. Follow the "With apt: Ubuntu, Debian" section, and the "Configuring Docker" section of the "Configuration" section. 
+
+[NVIDIA Container Toolkit Installation Guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)
+
+
+2. Verify that you've installed correctly using this command:
+```sudo docker run --rm --gpus all nvidia/cuda:11.0.3-base-ubuntu20.04 nvidia-smi```
+
+You should see something that looks like this pop up if successful. 
+
+
+![image/png](https://cdn-uploads.huggingface.co/production/uploads/64c9778db0e61287788a15c1/HCRGQUQzJCzUWUDbJX22v.png)
+
+If not, you should restart the NVIDIA Container Toolkit Installation Guide
+
+---
+
+### 4. Run the Docker Container
+
+Use the pre-configured Docker image provided by the Hugging Face Space:
+
+[Run Docker Container](https://huggingface.co/spaces/caltech-animal-tracking/Primate_Batch_Detection?docker=true)
+
+If you run into the "RuntimeError: Found no NVIDIA driver on your system" error, run this command instead. 
+
+
+```sudo docker run --rm -it --gpus all -p 7860:7860 registry.hf.space/caltech-animal-tracking-primate-batch-detection:latest python app_batch.py```
+
+**Note:** The first time you've installed the interface on a computer, it will take a while to download, but subsequent startups, just follow steps 4 and 5, and it should be relatively fast to start.
+
+### 5. Launch the interface
+
+Either click on the **local link** that is given in your WSL terminal, or go to this link in your web browser.
+
+<http:/localhost:7860>
+
+---
+
+## Troubleshooting Guide
+
+### 🚫 Error:
+The WSL window crashes immediately upon launch. 
+
+### 🛠️ Fix:  
+Double-check that you've done ```wsl --set-default Ubuntu``` in Powershell.
+
+### 🚫 Error:
+
+```docker: Error response from daemon: could not select device driver "" with capabilities: [[gpu]]```
+
+### 🛠️ Fix:  
+This typically means that the **NVIDIA Container Toolkit** was not installed or configured correctly. Double-check your installation by revisiting the [NVIDIA Container Toolkit Guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html).
+
+### 🚫 Error:
+```
+docker: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock:
+Head "http://%2Fvar%2Frun%2Fdocker.sock/_ping": dial unix /var/run/docker.sock: connect: permission denied
+```
+
+### 🛠️ Fix:
+This error occurs when your user does not have permission to access the Docker socket.
+
+You have two options:
+
+**Option 1: Add your user to the Docker group**
+```
+sudo usermod -aG docker $USER
+sudo systemctl restart docker  # May not be needed or available in WSL
+```
+Then restart your terminal or log out and back in for the group change to take effect.
+
+**Option 2: Use sudo for all your docker commands**
+```
+sudo docker $YOUR_COMMAND
+```