MetabarcodingSchool/OBIJupyterHub
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Correction of the doc #2

Merged
coissac merged 1 commits from push-zkpmmkmzmzwl into master 2025-10-15 13:37:49 +00:00
Conversation 0 Commits 1 Files Changed 2 +88 -95
2 changed files with 88 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files

183
Readme.md
View File

@@ -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-<username>
```
Replace `<username>` 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
```
```

0
setup.sh → start-jupyterhub.sh
View File