Merge pull request 'Correction of the doc' (#2) from push-zkpmmkmzmzwl into master

Reviewed-on: #2

Readme.md

@@ -1,13 +1,27 @@
 # JupyterHub Configuration with OrbStack on Mac (all in Docker)
 
 ## Prerequisites
-- OrbStack installed and running
 
-## File Structure
+You must have docker running on your computer
 
-Your `~/jupyterhub-tp` directory should contain:
+-   On MacOS, [OrbStack](https://orbstack.dev/ "A Docker implementation optimised for MacOS") is recommanded
+
+## 
+
+## Installation Steps
+
+### 1. Create Directory Structure
+
+``` bash
+git clone https://forge.metabarcoding.org/MetabarcodingSchool/OBIJupyterHub.git
 ```
-~/jupyterhub-tp/
+
+#### File Structure
+
+Your `~/OBIJupyterHub` directory should contain:
+
+```         
+~/OBIJupyterHub/
 ├── Dockerfile                  # Image for students (already created)
 ├── Dockerfile.hub              # Image for JupyterHub (new)
 ├── jupyterhub_config.py        # Configuration
@@ -15,37 +29,13 @@ Your `~/jupyterhub-tp` directory should contain:
 └── start-jupyterhub.sh         # Startup script
 ```
 
-## Installation Steps
+### 2. Start JupyterHub
-
-### 1. Create Directory Structure
-
-```bash
-mkdir -p ~/jupyterhub-tp
-cd ~/jupyterhub-tp
-```
-
-### 2. Create All Necessary Files
-
-Create the following files with the content from artifacts:
-- `Dockerfile` (artifact "Dockerfile for JupyterHub with R and Bash")
-- `Dockerfile.hub` (artifact "Dockerfile for JupyterHub container")
-- `jupyterhub_config.py` (artifact "JupyterHub Configuration")
-- `docker-compose.yml` (artifact "docker-compose.yml")
-- `start-jupyterhub.sh` (artifact "start-jupyterhub.sh")
-
-### 3. Make Startup Script Executable
-
-```bash
-chmod +x start-jupyterhub.sh
-```
-
-### 4. Start JupyterHub
 
 ``` bash
 ./start-jupyterhub.sh
 ```
 
-### 5. Access JupyterHub
+### 3. Access JupyterHub
 
 Open your browser and go to: **http://localhost:8888**
 
@@ -54,26 +44,31 @@ You can log in with any username and password: `metabar2025`
 ## Useful Commands
 
 ### View JupyterHub logs
+
 ``` bash
 docker-compose logs -f jupyterhub
 ```
 
 ### View all containers (hub + students)
+
 ``` bash
-docker ps
+docker ps | grep jupyterhub
 ```
 
 ### Stop JupyterHub
+
 ``` bash
 docker-compose down
 ```
 
 ### Restart JupyterHub (after config modification)
+
 ``` bash
 docker-compose restart jupyterhub
 ```
 
 ### Rebuild after Dockerfile modification
+
 ``` bash
 # For student image
 docker build -t jupyterhub-student:latest -f Dockerfile .
@@ -84,11 +79,15 @@ docker-compose up -d --build
 ```
 
 ### View logs for a specific student
+
 ``` bash
-docker logs jupyter-username
+docker logs jupyter-<username>
 ```
 
+Replace `<username>` by the actual user name of the student.
+
 ### Clean up after lab
+
 ``` bash
 # Stop and remove all containers
 docker-compose down
@@ -110,6 +109,7 @@ docker volume prune -f
 ### Directory Structure for Each Student
 
 Each student will see this directory structure in their JupyterLab (everything under `work/` is persistent):
+
 ```         
 work/                              # Personal workspace root (persistent)
 ├── [student files]               # Their own files and notebooks
@@ -121,24 +121,15 @@ work/                              # Personal workspace root (persistent)
     └── [course materials]        # Your course files
 ```
 
-**R Package Priority:**
+**R Package Priority:** 1. R checks `work/R_packages/` first (personal, writable) 2. Then `work/course/R_packages/` (shared, read-only, installed by prof) 3. Then system libraries
-1. R checks `work/R_packages/` first (personal, writable)
-2. Then `work/course/R_packages/` (shared, read-only, installed by prof)
-3. Then system libraries
 
 **Important:** Everything is under `work/`, so all student files are automatically saved in their persistent volume.
 
 ### User Accounts
 
-**Admin Account:**
+**Admin Account:** - Username: `admin` - Password: `admin2025` (change in docker-compose.yml: `JUPYTERHUB_ADMIN_PASSWORD`) - Can write to `course/` directory
-- Username: `admin`
-- Password: `admin2025` (change in docker-compose.yml: `JUPYTERHUB_ADMIN_PASSWORD`)
-- Can write to `course/` directory
 
-**Student Accounts:**
+**Student Accounts:** - Username: any name - Password: `metabar2025` (change in docker-compose.yml: `JUPYTERHUB_PASSWORD`) - Read-only access to `course/` directory
-- Username: any name
-- Password: `metabar2025` (change in docker-compose.yml: `JUPYTERHUB_PASSWORD`)
-- Read-only access to `course/` directory
 
 ### Installing R Packages (Admin Only)
 
@@ -151,10 +142,7 @@ chmod +x install-r-packages-admin.sh
 ./install-r-packages-admin.sh reshape2 plotly knitr
 ```
 
-This script:
+This script: - Installs packages in the `course/R_packages/` directory - All students can use them (read-only) - No need to rebuild the image
-- Installs packages in the `course/R_packages/` directory
-- All students can use them (read-only)
-- No need to rebuild the image
 
 **From admin notebook:**
 
@@ -184,15 +172,13 @@ install.packages(c('mypackage'))  # Will install in work/R_packages/
 ### Using R Packages (Students)
 
 Students simply load packages normally:
+
 ``` r
 library(reshape2)  # R checks: 1) work/R_packages/ 2) work/course/R_packages/ 3) system
 library(plotly)
 ```
 
-R automatically searches in this order:
+R automatically searches in this order: 1. Personal packages: `/home/jovyan/work/R_packages/` (R_LIBS_USER) 2. Prof packages: `/home/jovyan/work/course/R_packages/` (R_LIBS_SITE) 3. System packages
-1. Personal packages: `/home/jovyan/work/R_packages/` (R_LIBS_USER)
-2. Prof packages: `/home/jovyan/work/course/R_packages/` (R_LIBS_SITE)
-3. System packages
 
 ### List Available Packages
 
@@ -261,13 +247,17 @@ docker run --rm \
 ## User Management
 
 ### Option 1: Predefined User List
+
 In `jupyterhub_config.py`, uncomment and modify:
+
 ``` python
 c.Authenticator.allowed_users = {'student1', 'student2', 'student3'}
 ```
 
 ### Option 2: Allow Everyone (for testing)
+
 By default, the configuration allows any user:
+
 ``` python
 c.Authenticator.allow_all = True
 ```
@@ -276,40 +266,46 @@ c.Authenticator.allow_all = True
 
 ## Kernel Verification
 
-Once logged in, create a new notebook and verify you have access to:
+Once logged in, create a new notebook and verify you have access to: - **Python 3** (default kernel) - **R** (R kernel) - **Bash** (bash kernel)
-- **Python 3** (default kernel)
-- **R** (R kernel)
-- **Bash** (bash kernel)
 
 ## Customization for Your Labs
 
 ### Add Additional R Packages
+
 Modify the `Dockerfile` (before `USER ${NB_UID}`):
+
 ``` dockerfile
 RUN R -e "install.packages(c('your_package'), repos='http://cran.rstudio.com/')"
 ```
 
 Then rebuild:
+
 ``` bash
 docker build -t jupyterhub-student:latest -f Dockerfile .
 docker-compose restart jupyterhub
 ```
 
 ### Add Python Packages
+
 Add to the `Dockerfile` (before `USER ${NB_UID}`):
+
 ``` dockerfile
 RUN pip install numpy pandas matplotlib seaborn
 ```
 
 ### Distribute Files to Students
+
 Create a `files_lab/` directory and add to the `Dockerfile`:
+
 ``` dockerfile
 COPY files_lab/ /home/${NB_USER}/lab/
 RUN chown -R ${NB_UID}:${NB_GID} /home/${NB_USER}/lab
 ```
 
 ### Change Port (if 8000 is occupied)
+
 Modify in `docker-compose.yml`:
+
 ``` yaml
 ports:
   - "8001:8000"  # Accessible on localhost:8001
@@ -317,31 +313,28 @@ ports:
 
 ## Advantages of This Approach
 
-✅ **Everything in Docker**: No need to install Python/JupyterHub on your Mac  
+✅ **Everything in Docker**: No need to install Python/JupyterHub on your computer\
-✅ **Portable**: Easy to deploy on another Mac or server  
+✅ **Portable**: Easy to deploy on another server\
-✅ **Isolated**: No pollution of your system environment  
+✅ **Isolated**: No pollution of your system environment\
-✅ **Easy to Clean**: A simple `docker-compose down` is enough  
+✅ **Easy to Clean**: A simple `docker-compose down` is enough\
 ✅ **Reproducible**: Students will have exactly the same environment
 
 ## Troubleshooting
 
-**Error "Cannot connect to Docker daemon"**:
+**Error "Cannot connect to Docker daemon"**: - Check that OrbStack is running - Verify the socket exists: `ls -la /var/run/docker.sock`
-- Check that OrbStack is running
-- Verify the socket exists: `ls -la /var/run/docker.sock`
 
-**Student containers don't start**:
+**Student containers don't start**: - Check logs: `docker-compose logs jupyterhub` - Verify student image exists: `docker images | grep jupyterhub-student`
-- Check logs: `docker-compose logs jupyterhub`
-- Verify student image exists: `docker images | grep jupyterhub-student`
 
-**Port 8000 already in use**:
+**Port 8000 already in use**: - Change port in `docker-compose.yml`
-- Change port in `docker-compose.yml`
 
 **After config modification, changes are not applied**:
+
 ``` bash
 docker-compose restart jupyterhub
 ```
 
 **I want to start from scratch**:
+
 ``` bash
 docker-compose down -v
 docker rmi jupyterhub-hub jupyterhub-student