Merge pull request #17 from AMDResearch/develop

Pre-release v0.0.2

Author: KerwinTsaiii

.gitignore

@@ -368,3 +368,7 @@ vite.config.ts.timestamp-*
 
 # Project specific
 dockerfiles/Courses/DL/data/FashionMNIST/raw/
+
+# Local config overrides (any file containing 'local')
+*local*
+*.local.*

.vscode/settings.json

@@ -1,5 +1,9 @@
 {
   // Python
+  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+  "python.analysis.extraPaths": [
+    "${workspaceFolder}/runtime/jupyterhub/files/hub"
+  ],
   "[python]": {
     "editor.defaultFormatter": "charliermarsh.ruff",
     "editor.formatOnSave": true,

README.md

@@ -69,6 +69,7 @@ After installation completes, open http://localhost:30890 in your browser. No lo
 | `uninstall` | Complete removal of all components |
 | `upgrade-runtime` | Upgrade JupyterHub deployment |
 | `build-images` | Build and import container images |
+| `pull-images` | Pull external images for offline use |
 | `install-tools` | Install Helm and K9s only |
 | `install-runtime` | Deploy JupyterHub only |
 | `remove-runtime` | Remove JupyterHub only |
@@ -81,6 +82,8 @@ sudo ./single-node.sh upgrade-runtime
 # Rebuild images after modifying Dockerfiles
 sudo ./single-node.sh build-images
 ```
+
+> **💡 Tip**: If you need to use alternative container registries or package mirrors, see [Mirror Configuration](deploy/README.md#mirror-configuration).
 ## Manual Installation
 
 For users who prefer step-by-step manual installation or need more control over the deployment process:
@@ -143,6 +146,9 @@ Current environments are set up as `RESOURCE_IMAGES` in `runtime/jupyterhub/file
 ## Documentation
 
 - [JupyterHub Configuration](docs/jupyterhub/README.md) - Detailed JupyterHub settings
+- [Authentication Guide](docs/jupyterhub/authentication-guide.md) - GitHub OAuth and native authentication
+- [User Management Guide](docs/jupyterhub/user-management.md) - Batch user operations with scripts
+- [User Quota System](docs/jupyterhub/quota-system.md) - Resource usage tracking and quota management
 - [GitHub OAuth Setup](docs/jupyterhub/How_to_Setup_GitHub_OAuth.md) - OAuth configuration
 - [Maintenance Manual](docs/user-manual/aup-remote-lab-user-manual-admin-new.md) - Operations guide
 

deploy/README.md

@@ -46,6 +46,8 @@ cd aup-learning-cloud
 
 A simplified deployment for development, demos, or small-scale teaching environments.
 
+> **💡 Tip**: If you need to use alternative container registries or package mirrors, see [Mirror Configuration](#mirror-configuration).
+
 ### Prerequisites
 
 **Hardware**
@@ -445,3 +447,66 @@ echo $PATH
 
 # Reinstall helm if needed (see Step 2 in deployment guides above)
 ```
+
+---
+
+## Advanced Configuration
+
+### Offline / Portable Operation
+
+The single-node deployment script automatically configures the system for offline and portable operation. When you run `./single-node.sh install`, it:
+
+1. **Creates a dummy network interface** (`dummy0`) with a stable IP address (`10.255.255.1`)
+2. **Binds K3s to the dummy interface** using `--node-ip` and `--flannel-iface`
+3. **Pre-pulls all required container images** to local storage
+4. **Configures K3s to use local images** from `/var/lib/rancher/k3s/agent/images/`
+
+This ensures the cluster remains fully functional even when:
+- External network is disconnected (network cable unplugged)
+- WiFi network changes (connecting to different access points)
+- No network is available at all
+
+**How it works**: K3s is bound to a stable dummy interface IP instead of the physical network interface. This means K3s doesn't care about external network changes - it always uses the same internal IP for cluster communication.
+
+**Reference**: [K3s Air-Gap Installation](https://docs.k3s.io/installation/airgap)
+
+### Mirror Configuration
+
+If you need to use alternative mirrors for container registries or package managers, you can configure them via environment variables when running the deployment script.
+
+#### Container Registry Mirror
+
+Set `MIRROR_PREFIX` to use a registry mirror that supports the **universal prefix mode**. The prefix will be prepended to all container image references:
+
+```bash
+# Example: quay.io/jupyterhub/k8s-hub:4.1.0 becomes
+#          mirror.example.com/quay.io/jupyterhub/k8s-hub:4.1.0
+
+MIRROR_PREFIX="mirror.example.com" ./single-node.sh install
+```
+
+> **Note**: This configuration works with registry mirrors that support the universal prefix pattern (e.g., `mirror/registry.k8s.io/image`). Some mirror services use per-registry subdomains instead (e.g., `k8s.mirror.org/image`), which require manual K3s registry configuration. See [K3s Private Registry Configuration](https://docs.k3s.io/installation/private-registry) for details.
+
+#### Package Manager Mirrors
+
+Set `MIRROR_PIP` and `MIRROR_NPM` to use alternative package repositories during image builds:
+
+```bash
+MIRROR_PIP="https://pypi.example.com/simple" \
+MIRROR_NPM="https://registry.example.com" \
+./single-node.sh build-images
+```
+
+#### Combined Example
+
+```bash
+MIRROR_PREFIX="mirror.example.com" \
+MIRROR_PIP="https://pypi.example.com/simple" \
+MIRROR_NPM="https://registry.example.com" \
+./single-node.sh install
+```
+
+For available environment variables, run:
+```bash
+./single-node.sh help
+```