diff --git a/Readme.md b/Readme.md index 55d6542..6686220 100644 --- a/Readme.md +++ b/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 +``` bash ./start-jupyterhub.sh ``` -### 5. Access JupyterHub +### 3. Access JupyterHub Open your browser and go to: **http://localhost:8888** @@ -54,27 +44,32 @@ You can log in with any username and password: `metabar2025` ## Useful Commands ### View JupyterHub logs -```bash + +``` bash docker-compose logs -f jupyterhub ``` ### View all containers (hub + students) -```bash -docker ps + +``` bash +docker ps | grep jupyterhub ``` ### Stop JupyterHub -```bash + +``` bash docker-compose down ``` ### Restart JupyterHub (after config modification) -```bash + +``` bash docker-compose restart jupyterhub ``` ### Rebuild after Dockerfile modification -```bash + +``` bash # For student image docker build -t jupyterhub-student:latest -f Dockerfile . docker-compose restart jupyterhub @@ -84,12 +79,16 @@ docker-compose up -d --build ``` ### View logs for a specific student -```bash -docker logs jupyter-username + +``` bash +docker logs jupyter- ``` +Replace `` by the actual user name of the student. + ### Clean up after lab -```bash + +``` bash # Stop and remove all containers docker-compose down @@ -110,7 +109,8 @@ 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 ├── R_packages/ # Personal R packages (writable by student) @@ -121,46 +121,34 @@ work/ # Personal workspace root (persistent) └── [course materials] # Your course files ``` -**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 +**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 **Important:** Everything is under `work/`, so all student files are automatically saved in their persistent volume. ### User Accounts -**Admin Account:** -- Username: `admin` -- Password: `admin2025` (change in docker-compose.yml: `JUPYTERHUB_ADMIN_PASSWORD`) -- Can write to `course/` directory +**Admin Account:** - Username: `admin` - Password: `admin2025` (change in docker-compose.yml: `JUPYTERHUB_ADMIN_PASSWORD`) - Can write to `course/` directory -**Student Accounts:** -- Username: any name -- Password: `metabar2025` (change in docker-compose.yml: `JUPYTERHUB_PASSWORD`) -- Read-only access to `course/` directory +**Student Accounts:** - Username: any name - Password: `metabar2025` (change in docker-compose.yml: `JUPYTERHUB_PASSWORD`) - Read-only access to `course/` directory ### Installing R Packages (Admin Only) **From your Mac (recommended):** -```bash +``` bash chmod +x install-r-packages-admin.sh # Install packages ./install-r-packages-admin.sh reshape2 plotly knitr ``` -This script: -- Installs packages in the `course/R_packages/` directory -- All students can use them (read-only) -- No need to rebuild the image +This script: - Installs packages in the `course/R_packages/` directory - All students can use them (read-only) - No need to rebuild the image **From admin notebook:** Login as `admin` and create an R notebook: -```r +``` r # Install packages in course/R_packages (admin only, available to all students) course_lib <- "/home/jovyan/work/course/R_packages" dir.create(course_lib, recursive = TRUE, showWarnings = FALSE) @@ -176,7 +164,7 @@ Note: Admin account has write access to the course directory. Students can install packages in their personal `work/R_packages/`: -```r +``` r # Install in personal library (each student has their own) install.packages(c('mypackage')) # Will install in work/R_packages/ ``` @@ -184,19 +172,17 @@ install.packages(c('mypackage')) # Will install in work/R_packages/ ### Using R Packages (Students) Students simply load packages normally: -```r + +``` r library(reshape2) # R checks: 1) work/R_packages/ 2) work/course/R_packages/ 3) system library(plotly) ``` -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 +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 ### List Available Packages -```r +``` r # List all available packages (personal + course + system) installed.packages()[,"Package"] @@ -211,7 +197,7 @@ list.files("/home/jovyan/work/course/R_packages") To put files in the `course/` directory (accessible read-only): -```bash +``` bash # Create a temporary directory mkdir -p ~/jupyterhub-tp/course-files @@ -230,7 +216,7 @@ docker run --rm \ Students can collaborate via the `shared/` directory: -```python +``` python # In a notebook, to read a shared file import pandas as pd df = pd.read_csv('/home/jovyan/work/shared/group_data.csv') @@ -241,7 +227,7 @@ df.to_csv('/home/jovyan/work/shared/alice_results.csv') ### Retrieve Student Work -```bash +``` bash # List user volumes docker volume ls | grep jupyterhub-user @@ -261,14 +247,18 @@ docker run --rm \ ## User Management ### Option 1: Predefined User List + In `jupyterhub_config.py`, uncomment and modify: -```python + +``` python c.Authenticator.allowed_users = {'student1', 'student2', 'student3'} ``` ### Option 2: Allow Everyone (for testing) + By default, the configuration allows any user: -```python + +``` python c.Authenticator.allow_all = True ``` @@ -276,75 +266,78 @@ c.Authenticator.allow_all = True ## Kernel Verification -Once logged in, create a new notebook and verify you have access to: -- **Python 3** (default kernel) -- **R** (R kernel) -- **Bash** (bash kernel) +Once logged in, create a new notebook and verify you have access to: - **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 + +``` dockerfile RUN R -e "install.packages(c('your_package'), repos='http://cran.rstudio.com/')" ``` Then rebuild: -```bash + +``` 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 + +``` dockerfile RUN pip install numpy pandas matplotlib seaborn ``` ### Distribute Files to Students + Create a `files_lab/` directory and add to the `Dockerfile`: -```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 + +``` yaml ports: - "8001:8000" # Accessible on localhost:8001 ``` ## Advantages of This Approach -✅ **Everything in Docker**: No need to install Python/JupyterHub on your Mac -✅ **Portable**: Easy to deploy on another Mac or server -✅ **Isolated**: No pollution of your system environment -✅ **Easy to Clean**: A simple `docker-compose down` is enough +✅ **Everything in Docker**: No need to install Python/JupyterHub on your computer\ +✅ **Portable**: Easy to deploy on another server\ +✅ **Isolated**: No pollution of your system environment\ +✅ **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"**: -- Check that OrbStack is running -- Verify the socket exists: `ls -la /var/run/docker.sock` +**Error "Cannot connect to Docker daemon"**: - Check that OrbStack is running - Verify the socket exists: `ls -la /var/run/docker.sock` -**Student containers don't start**: -- Check logs: `docker-compose logs jupyterhub` -- Verify student image exists: `docker images | grep jupyterhub-student` +**Student containers don't start**: - Check logs: `docker-compose logs jupyterhub` - Verify student image exists: `docker images | grep jupyterhub-student` -**Port 8000 already in use**: -- Change port in `docker-compose.yml` +**Port 8000 already in use**: - Change port in `docker-compose.yml` **After config modification, changes are not applied**: -```bash + +``` bash docker-compose restart jupyterhub ``` **I want to start from scratch**: -```bash + +``` bash docker-compose down -v docker rmi jupyterhub-hub jupyterhub-student # Then rebuild everything ./start-jupyterhub.sh -``` +``` \ No newline at end of file diff --git a/setup.sh b/start-jupyterhub.sh similarity index 100% rename from setup.sh rename to start-jupyterhub.sh