ethoscopy 2.0.4__tar.gz → 2.0.5__tar.gz

ethoscopy-2.0.5/.claude/settings.local.json

@@ -0,0 +1,40 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(wc:*)",
+      "Bash(paplay:*)",
+      "Bash(ETHOSCOPE_DATA_PATH=/mnt/ethoscope_data docker compose:*)",
+      "Bash(docker ps:*)",
+      "Bash(docker logs:*)",
+      "Bash(docker compose:*)",
+      "Bash(curl:*)",
+      "Bash(docker exec:*)",
+      "Bash(mkdir -p /tmp/ethoscopy_wheel_inspect)",
+      "Read(//tmp/**)",
+      "Bash(pip download *)",
+      "Bash(unzip -l ethoscopy-2.0.4-py3-none-any.whl)",
+      "Bash(git check-ignore *)",
+      "Bash(/home/gg/Code/ethoscope_project/ethoscopy/.venv/bin/pip install *)",
+      "Bash(.venv/bin/python -m pytest tests/test_get_tutorials.py -v)",
+      "Bash(.venv/bin/python *)",
+      "Bash(.venv/bin/pip install *)",
+      "Bash(gh auth *)",
+      "Bash(gh repo *)",
+      "Bash(docker info *)",
+      "mcp__bookstack__bookstack_search",
+      "Bash(.venv/bin/ruff check *)",
+      "Bash(.venv/bin/black --check src/ tests/)",
+      "Bash(.venv/bin/black src/ethoscopy/misc/get_tutorials.py tests/test_get_tutorials.py)",
+      "mcp__bookstack__bookstack_pages_read",
+      "mcp__bookstack__bookstack_pages_update",
+      "Bash(gh issue create --repo gilestrolab/ethoscopy --title 'Tutorial data pickles missing from PyPI wheel \\(2.0.0 – 2.0.4\\)' --body ' *)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(git push *)",
+      "Bash(git tag *)",
+      "Bash(gh release create v2.0.5 --repo gilestrolab/ethoscopy --title 'v2.0.5 — package tutorial data separately' --notes ' *)",
+      "Bash(gh run *)",
+      "Bash(gh issue *)"
+    ]
+  }
+}

{ethoscopy-2.0.4 → ethoscopy-2.0.5}/.pre-commit-config.yaml

@@ -51,7 +51,7 @@ repos:
         language: system
         pass_filenames: false
         always_run: true
-        stages: [commit]
+        stages: [pre-commit]
 
       - id: pytest-fast
         name: pytest-fast
@@ -59,4 +59,4 @@ repos:
         language: system
         pass_filenames: false
         always_run: true
-        stages: [push]
+        stages: [pre-push]

ethoscopy-2.0.5/Docker/.env.dummy.example

@@ -0,0 +1,25 @@
+# ============================================================================
+# DUMMY AUTHENTICATOR (Simple Shared Password)
+# ============================================================================
+# Default authentication method - all users share the same password
+# Best for: Lab environments, small teams, trusted networks
+
+# Authenticator type (must be 'dummy' for this configuration)
+AUTHENTICATOR_CLASS=dummy
+
+# Shared password for all users
+DUMMY_PASSWORD=ethoscope
+
+# Comma-separated list of allowed users
+ALLOWED_USERS=amadabhushi,ggilestro,mjoyce,lguo,labguest1,labguest2,labguest3,labguest4,labguest5,labguest6,labguest7,labguest8,ethoscopelab
+
+# Comma-separated list of admin users
+ADMIN_USERS=ggilestro
+
+# Docker user/group (optional, defaults to 1000:1000)
+UID=1000
+GID=1000
+
+# JupyterHub and Ethoscope Lab versions
+JUPYTER_HUB_TAG=5.3.0
+ETHOSCOPE_LAB_TAG=1.1

ethoscopy-2.0.5/Docker/.env.github.example

@@ -0,0 +1,39 @@
+# ============================================================================
+# GITHUB OAUTH AUTHENTICATOR
+# ============================================================================
+# Authenticate users via their GitHub accounts
+# Best for: Open source projects, teams already using GitHub
+#
+# Setup Instructions:
+# 1. Go to GitHub Settings > Developer Settings > OAuth Apps
+# 2. Create a new OAuth App
+# 3. Set Homepage URL: http://your-server:8082
+# 4. Set Authorization callback URL: http://your-server:8082/hub/oauth_callback
+# 5. Copy the Client ID and generate a Client Secret
+
+# Authenticator type
+AUTHENTICATOR_CLASS=github
+
+# OAuth credentials from GitHub OAuth App
+OAUTH_CLIENT_ID=your_github_client_id_here
+OAUTH_CLIENT_SECRET=your_github_client_secret_here
+
+# Callback URL (must match what you set in GitHub OAuth App)
+OAUTH_CALLBACK_URL=http://your-server:8082/hub/oauth_callback
+
+# (Optional) Restrict to GitHub organization members
+# GITHUB_ORG=your-organization-name
+
+# Comma-separated list of allowed users (GitHub usernames)
+ALLOWED_USERS=username1,username2,username3
+
+# Comma-separated list of admin users (GitHub usernames)
+ADMIN_USERS=your-github-username
+
+# Docker user/group (optional, defaults to 1000:1000)
+UID=1000
+GID=1000
+
+# JupyterHub and Ethoscope Lab versions
+JUPYTER_HUB_TAG=5.3.0
+ETHOSCOPE_LAB_TAG=1.1

ethoscopy-2.0.5/Docker/.env.google.example

@@ -0,0 +1,41 @@
+# ============================================================================
+# GOOGLE OAUTH AUTHENTICATOR
+# ============================================================================
+# Authenticate users via their Google accounts
+# Best for: Organizations using Google Workspace, universities with Google
+#
+# Setup Instructions:
+# 1. Go to Google Cloud Console (console.cloud.google.com)
+# 2. Create a new project or select existing
+# 3. Enable Google+ API
+# 4. Go to Credentials > Create Credentials > OAuth 2.0 Client ID
+# 5. Set Application type: Web application
+# 6. Add Authorized redirect URI: http://your-server:8082/hub/oauth_callback
+# 7. Copy the Client ID and Client Secret
+
+# Authenticator type
+AUTHENTICATOR_CLASS=google
+
+# OAuth credentials from Google Cloud Console
+OAUTH_CLIENT_ID=your_google_client_id.apps.googleusercontent.com
+OAUTH_CLIENT_SECRET=your_google_client_secret_here
+
+# Callback URL (must match what you set in Google Cloud Console)
+OAUTH_CALLBACK_URL=http://your-server:8082/hub/oauth_callback
+
+# (Optional) Restrict to Google Workspace domain
+# GOOGLE_HOSTED_DOMAIN=yourdomain.com
+
+# Comma-separated list of allowed users (Gmail addresses without @gmail.com or @yourdomain.com)
+ALLOWED_USERS=user1,user2,user3
+
+# Comma-separated list of admin users
+ADMIN_USERS=your-email-username
+
+# Docker user/group (optional, defaults to 1000:1000)
+UID=1000
+GID=1000
+
+# JupyterHub and Ethoscope Lab versions
+JUPYTER_HUB_TAG=5.3.0
+ETHOSCOPE_LAB_TAG=1.1

ethoscopy-2.0.5/Docker/.env.keycloak.example

@@ -0,0 +1,53 @@
+# ============================================================================
+# KEYCLOAK / GENERIC OIDC AUTHENTICATOR
+# ============================================================================
+# Authenticate users via Keycloak or any OIDC-compliant provider
+# Best for: Organizations with existing SSO, enterprise environments
+#
+# Setup Instructions for Keycloak:
+# 1. Log into your Keycloak Admin Console
+# 2. Select your realm (e.g., 'gilestro-lab')
+# 3. Go to Clients > Create Client
+# 4. Set Client ID: jupyterhub
+# 5. Set Client Protocol: openid-connect
+# 6. Set Access Type: confidential
+# 7. Set Valid Redirect URIs: http://your-server:8082/hub/oauth_callback
+# 8. Save and go to Credentials tab to get the Client Secret
+# 9. Create users in Keycloak matching your existing home directory names
+
+# Authenticator type
+AUTHENTICATOR_CLASS=generic
+
+# OAuth credentials from Keycloak client
+OAUTH_CLIENT_ID=jupyterhub
+OAUTH_CLIENT_SECRET=your_keycloak_client_secret_here
+
+# Callback URL
+OAUTH_CALLBACK_URL=http://your-server:8082/hub/oauth_callback
+
+# Keycloak OIDC endpoints (replace YOUR_KEYCLOAK_SERVER and YOUR_REALM)
+# Example: http://keycloak.example.com/realms/gilestro-lab
+OAUTH_AUTHORIZE_URL=http://YOUR_KEYCLOAK_SERVER/realms/YOUR_REALM/protocol/openid-connect/auth
+OAUTH_TOKEN_URL=http://YOUR_KEYCLOAK_SERVER/realms/YOUR_REALM/protocol/openid-connect/token
+OAUTH_USERDATA_URL=http://YOUR_KEYCLOAK_SERVER/realms/YOUR_REALM/protocol/openid-connect/userinfo
+
+# Username claim (Keycloak uses 'preferred_username' by default)
+OAUTH_USERNAME_CLAIM=preferred_username
+
+# OAuth scopes (comma-separated, optional)
+OAUTH_SCOPE=openid,profile,email
+
+# CRITICAL: Keycloak usernames MUST match existing home directory names exactly
+# Comma-separated list of allowed users
+ALLOWED_USERS=amadabhushi,ggilestro,mjoyce,lguo,labguest1,labguest2,labguest3,labguest4,labguest5,labguest6,labguest7,labguest8,ethoscopelab
+
+# Comma-separated list of admin users
+ADMIN_USERS=ggilestro
+
+# Docker user/group (optional, defaults to 1000:1000)
+UID=1000
+GID=1000
+
+# JupyterHub and Ethoscope Lab versions
+JUPYTER_HUB_TAG=5.3.0
+ETHOSCOPE_LAB_TAG=1.1

{ethoscopy-2.0.4 → ethoscopy-2.0.5}/Docker/Dockerfile

@@ -70,16 +70,23 @@ RUN pip3 install jupyterlab-spreadsheet-editor
 # ============================================================================
 
 # Install Python data science packages
+# Including oauthenticator for flexible authentication support
 RUN pip3 install \
+        oauthenticator \
         pandas \
         seaborn \
         bokeh \
         lifelines \
         opencv-python \
         mysql-connector \
-        ethoscopy 
+        ethoscopy
        # pycatch22
 
+# Pre-populate tutorial datasets inside the installed package so non-root
+# JupyterHub users don't have to download them on first notebook run. The
+# pickles (~36 MB total) live in the ethoscopy repo, not the PyPI wheel.
+RUN python3 -c "from ethoscopy.misc.get_tutorials import download_tutorial_data, package_tutorial_data_dir; download_tutorial_data(dest_dir=package_tutorial_data_dir(), verbose=True)"
+
 # Install Ethoscope from source
 RUN git clone https://github.com/gilestrolab/ethoscope.git /opt/ethoscope && \
     cd /opt/ethoscope/ && git checkout dev && \

{ethoscopy-2.0.4 → ethoscopy-2.0.5}/Docker/README.md

@@ -12,43 +12,36 @@ The command to use to recreate that image is `JUPYTER_HUB_TAG=5.3.0 ETHOSCOPE_LA
 
 After creation, the image can be run using the enclosed `docker-compose.yml` file, replacing values as fit.
 
-## Add new users to the JupyterHub
+## Authentication and User Management
 
-To add new users to the JupyterHub instance:
+This JupyterHub instance supports multiple authentication methods including:
+- **Keycloak OAuth** (current production setup at auth.gilest.ro)
+- GitHub OAuth
+- Google OAuth
+- GitLab OAuth
+- Dummy authenticator (shared password)
 
-### 1. Modify the jupyterhub_config.py file
+### Adding New Users
 
-Edit the `allowed_users` set on lines 14-19 to include your new usernames:
+**⚠️ Important**: Adding a new user requires steps on BOTH the authentication provider AND the JupyterHub host.
 
-```python
-c.Authenticator.allowed_users = {
-    'amadabhushi', 'ggilestro', 'mjoyce', 'lguo',
-    'labguest1', 'labguest2', 'labguest3', 'labguest4',
-    'labguest5', 'labguest6', 'labguest7', 'labguest8',
-    'ethoscopelab', 'newuser1', 'newuser2'  # Add your new users here
-}
-```
-
-To make a user an admin, add them to the `admin_users` set on line 22:
+For detailed instructions on adding users, making users admins, and switching authentication methods, see:
 
-```python
-c.Authenticator.admin_users = {'ggilestro', 'newadmin'}
-```
+**📖 [README_AUTH.md](./README_AUTH.md) - Complete Authentication and User Management Guide**
 
-### 2. Restart the Docker container
+### Quick Reference
 
-After modifying the config file:
+**For Keycloak (current setup)**:
+1. Add user to Keycloak at `auth.gilest.ro` in the `gilestro-lab` realm
+2. Create home directory on host: `sudo mkdir -p /mnt/homes/username && sudo chown 1000:1000 /mnt/homes/username`
+3. (Optional) Add to `config/users.py` if using whitelist enforcement
 
-```bash
-docker compose down
-docker compose up -d
-```
+**For Dummy Auth**:
+1. Add username to `config/users.py` or `.env` file
+2. Create home directory on host
+3. Restart container
 
-**Notes:**
-- All users share the same password: `ethoscope` (line 11)
-- The system uses DummyAuthenticator for simple shared-password authentication
-- Each user gets their own home directory at `/home/{username}`
-- Home directories are created automatically when users first log in
+See [README_AUTH.md](./README_AUTH.md) for complete step-by-step instructions.
 
 ## Mounting Home Directories as Volumes