diff --git a/source/_static/images/user-guide/code-server-main-interface.png b/source/_static/images/user-guide/code-server-main-interface.png new file mode 100644 index 00000000..60d22cbf Binary files /dev/null and b/source/_static/images/user-guide/code-server-main-interface.png differ diff --git a/source/_static/images/user-guide/code-server-selection.png b/source/_static/images/user-guide/code-server-selection.png new file mode 100644 index 00000000..d403636b Binary files /dev/null and b/source/_static/images/user-guide/code-server-selection.png differ diff --git a/source/_static/images/user-guide/extensions-panel.png b/source/_static/images/user-guide/extensions-panel.png new file mode 100644 index 00000000..ce55709d Binary files /dev/null and b/source/_static/images/user-guide/extensions-panel.png differ diff --git a/source/_static/images/user-guide/github-login.png b/source/_static/images/user-guide/github-login.png new file mode 100644 index 00000000..53a63ba3 Binary files /dev/null and b/source/_static/images/user-guide/github-login.png differ diff --git a/source/_static/images/user-guide/jupyterlab-launcher.png b/source/_static/images/user-guide/jupyterlab-launcher.png new file mode 100644 index 00000000..b5c91ce1 Binary files /dev/null and b/source/_static/images/user-guide/jupyterlab-launcher.png differ diff --git a/source/_static/images/user-guide/jupyterlab-selection.png b/source/_static/images/user-guide/jupyterlab-selection.png new file mode 100644 index 00000000..a0869feb Binary files /dev/null and b/source/_static/images/user-guide/jupyterlab-selection.png differ diff --git a/source/_static/images/user-guide/launch-server.png b/source/_static/images/user-guide/launch-server.png new file mode 100644 index 00000000..8c9a3697 Binary files /dev/null and b/source/_static/images/user-guide/launch-server.png differ diff --git a/source/_static/images/user-guide/platform-login-page.png b/source/_static/images/user-guide/platform-login-page.png new file mode 100644 index 00000000..acc3895b Binary files /dev/null and b/source/_static/images/user-guide/platform-login-page.png differ diff --git a/source/_static/images/user-guide/ports-panel.png b/source/_static/images/user-guide/ports-panel.png new file mode 100644 index 00000000..1ed3d425 Binary files /dev/null and b/source/_static/images/user-guide/ports-panel.png differ diff --git a/source/_static/images/user-guide/resource-selection-page.png b/source/_static/images/user-guide/resource-selection-page.png new file mode 100644 index 00000000..f466a91d Binary files /dev/null and b/source/_static/images/user-guide/resource-selection-page.png differ diff --git a/source/_static/images/user-guide/stop-my-server.png b/source/_static/images/user-guide/stop-my-server.png new file mode 100644 index 00000000..e8069849 Binary files /dev/null and b/source/_static/images/user-guide/stop-my-server.png differ diff --git a/source/user-guide/admin-manual.md b/source/jupyterhub/admin-manual.md similarity index 95% rename from source/user-guide/admin-manual.md rename to source/jupyterhub/admin-manual.md index 636b8f42..f2dbbed0 100644 --- a/source/user-guide/admin-manual.md +++ b/source/jupyterhub/admin-manual.md @@ -2,7 +2,7 @@ This page summarizes the current administrator-facing workflows. -For value-by-value configuration, use the [Configuration Reference](../jupyterhub/configuration-reference.md). +For value-by-value configuration, use the [Configuration Reference](configuration-reference.md). ## Admin Surfaces @@ -73,7 +73,7 @@ If quota is enabled, administrators can: - grant unlimited quota - inspect usage detail from the admin UI -See [User Quota System](../jupyterhub/quota-system.md) for details. +See [User Quota System](quota-system.md) for details. ### Update Login / Home Announcement diff --git a/source/jupyterhub/index.md b/source/jupyterhub/index.md index bf81bd18..6bdacaf8 100644 --- a/source/jupyterhub/index.md +++ b/source/jupyterhub/index.md @@ -9,6 +9,7 @@ configuration-reference README authentication-guide user-management +admin-manual quota-system github-oauth-setup ``` @@ -19,5 +20,6 @@ github-oauth-setup - {doc}`README` - Quick setup notes for runtime/values.yaml - {doc}`authentication-guide` - Setup authentication - {doc}`user-management` - Manage users +- {doc}`admin-manual` - Run common administrator workflows - {doc}`quota-system` - Configure quotas - {doc}`github-oauth-setup` - GitHub OAuth setup diff --git a/source/user-guide/code-server-guide.md b/source/user-guide/code-server-guide.md new file mode 100644 index 00000000..8239e99e --- /dev/null +++ b/source/user-guide/code-server-guide.md @@ -0,0 +1,177 @@ +# Code Server Guide + +This guide explains how to use Code Server in AUP Learning Cloud. Code Server provides a browser-based VS Code experience for coding, terminals, extensions, debugging, and web application previews. + +For login, environment selection, storage, and stopping servers, start with [Platform Basics](platform-basics.md). + +## When To Use Code Server + +Use Code Server when you want to: + +- Work in a VS Code-style editor from the browser +- Use integrated terminals +- Run scripts, training jobs, or development servers +- Install editor extensions +- Preview web applications through forwarded ports +- Work with multi-file projects or Git repositories + +If your task is mainly notebook-based, use [JupyterLab Guide](jupyterlab-guide.md). + +## Start A Code Server Environment + +1. Sign in to AUP Learning Cloud. +2. Select **Code Server CPU Environment** or **Code Server GPU Environment**. +3. Choose the required hardware resources. +4. Choose the runtime duration. +5. Click **Launch Server**. +6. Wait for the browser to open the VS Code interface. + +![Code Server selection](../_static/images/user-guide/code-server-selection.png) + +## Interface Overview + +The Code Server interface is similar to local VS Code: + +- Left side: Explorer, Search, Source Control, Run and Debug, Extensions +- Center: code editor +- Bottom panel: Terminal, Ports, Output, Problems + +![Code Server main interface](../_static/images/user-guide/code-server-main-interface.png) + +## Use The Terminal + +Open the integrated terminal with `Ctrl + \`` or from the top menu. + +Common commands: + +```bash +# Check GPU status in GPU environments +rocm-smi + +# Install Python packages +pip install torch torchvision + +# Run a script +python train.py + +# Start a simple web server +python -m http.server 8080 +``` + +You can open multiple terminal sessions by clicking the `+` button in the terminal panel. + +## Save Files + +Use the same storage rules as other AUP Learning Cloud environments: + +- Save important work under `/home/jovyan`. +- Do not rely on temporary or image-provided directories for long-term storage. +- Copy work to `/home/jovyan` before stopping the server. + +Example: + +```bash +cp /home/jovyan/ +``` + +## Port Forwarding + +When you run a web service inside Code Server, the platform can expose it through the browser. + +Example: + +```bash +python -m http.server 8080 +``` + +After the service starts: + +1. Open the **PORTS** panel. +2. Select the forwarded port and open the forwarded address. +3. If a notification appears, you can also click **Open in Browser**. +4. If the port does not appear automatically, add it manually in the **PORTS** panel. + +![Ports panel](../_static/images/user-guide/ports-panel.png) + +Forwarded URLs usually follow this pattern: + +```text +https://www.openhw.io/user//proxy// +``` + +Example: + +```text +https://www.openhw.io/user/github%3Ausername/proxy/3000/ +``` + +:::{note} +Port forwarding works for HTTP and WebSocket services that listen on a port inside your remote environment. Make sure your application is actually running and listening on the expected port. +::: + +## Extensions + +Code Server supports many VS Code extensions. Common preinstalled extensions may include: + +| Extension | Purpose | +|---|---| +| Python | Python language support, IntelliSense, and debugging | +| Jupyter | Notebook support inside VS Code | +| GitLens | Git history, blame, and comparison tools | +| Python Debugger | Python breakpoint debugging | +| Ruff | Python formatting and linting | +| YAML | YAML syntax support | + +To install an extension: + +1. Open the Extensions panel on the left. +2. Search for the extension name. +3. Click **Install**. + +![Extensions panel](../_static/images/user-guide/extensions-panel.png) + +Recommended extensions for some workflows: + +- C/C++: C/C++ development support +- ROCm HIP: AMD GPU programming support +- Remote - Containers: container development support +- Thunder Client: lightweight API testing +- Markdown Preview: live Markdown preview + +:::{note} +Extensions are installed in the remote environment. After a server restart or image change, you may need to install some extensions again. Keep a short list of your commonly used extensions. +::: + +## Stop Code Server + +Before leaving: + +1. Save your files. +2. Stop long-running terminal processes that you no longer need. +3. Copy important work to `/home/jovyan`. +4. Return to the Hub control page. +5. Click **Stop my server**. + +## Troubleshooting + +### Port forwarding does not work + +- Confirm the service is running. +- Confirm the service is listening on the expected port. +- Check the **PORTS** panel. +- Add the port manually if needed. +- Refresh the browser page and try again. + +### Extension installation fails + +- Check the network connection. +- Refresh the page and try again. +- Search for an alternative extension. +- Some desktop-only extensions may not fully support browser-based VS Code. + +### The terminal command cannot find a file + +- Check the current directory with `pwd`. +- List files with `ls`. +- Use absolute paths when needed. +- Confirm important files are stored under `/home/jovyan`. diff --git a/source/user-guide/index.md b/source/user-guide/index.md index b2a09186..7bd68fec 100644 --- a/source/user-guide/index.md +++ b/source/user-guide/index.md @@ -1,20 +1,18 @@ # User Guide -This section provides guides for users and administrators of AUP Learning Cloud. +This section provides end-user guides for AUP Learning Cloud. ```{toctree} :maxdepth: 2 -admin-manual +platform-basics +jupyterlab-guide +code-server-guide ``` -## For Administrators - -- {doc}`admin-manual` - Comprehensive guide for system administrators - ## For Users -End-user topics are summarized in **Quick Links** below. For login and authentication, see the [Authentication Guide](../jupyterhub/authentication-guide.md). Your administrator can provide the JupyterHub URL; once logged in you can: +Start with [Platform Basics](platform-basics.md) for login, environment selection, storage, and server lifecycle. Then use [JupyterLab Guide](jupyterlab-guide.md) or [Code Server Guide](code-server-guide.md) depending on the environment you launch. For authentication details, see the [Authentication Guide](../jupyterhub/authentication-guide.md). Your administrator can provide the JupyterHub URL; once logged in you can: - Launch notebook environments (Base CPU, GPU Base, CV/DL/LLM/PhySim courses) - Use hardware acceleration options (CPU, GPU) as allowed for your account diff --git a/source/user-guide/jupyterlab-guide.md b/source/user-guide/jupyterlab-guide.md new file mode 100644 index 00000000..f1136b75 --- /dev/null +++ b/source/user-guide/jupyterlab-guide.md @@ -0,0 +1,126 @@ +# JupyterLab Guide + +This guide explains how to use the JupyterLab environment in AUP Learning Cloud for notebooks, Python experiments, course materials, and terminal access. + +For login, environment selection, storage, and stopping servers, start with [Platform Basics](platform-basics.md). + +## When To Use JupyterLab + +Use JupyterLab when you want to: + +- Run Jupyter notebooks for course labs +- Execute Python code interactively +- Read and modify course-provided notebooks +- Use a terminal for simple commands +- Save experiment results in your user directory + +If you need a full VS Code-style IDE, use [Code Server Guide](code-server-guide.md) instead. + +## Start A JupyterLab Environment + +1. Sign in to AUP Learning Cloud. +2. Select a course, tutorial, test, or notebook environment. +3. Choose CPU or GPU resources if options are available. +4. Choose the runtime duration. +5. Click **Launch Server**. +6. Wait for the browser to open JupyterLab. + +![JupyterLab environment selection](../_static/images/user-guide/jupyterlab-selection.png) + +## Create A Notebook + +1. In the Launcher page, choose **Python 3**. +2. A new notebook opens in the main work area. +3. Type code in a cell. +4. Press `Shift + Enter` to run the cell. + +Example: + +```python +print("Hello, JupyterHub!") +``` + +![JupyterLab Launcher](../_static/images/user-guide/jupyterlab-launcher.png) + +## Run Notebook Cells + +Common actions: + +| Action | Shortcut | +|---|---| +| Run current cell | `Shift + Enter` | +| Save notebook | `Ctrl + S` on Windows/Linux, `Cmd + S` on macOS | +| Add a new cell | Use the notebook toolbar `+` button | +| Change cell type | Use the cell type dropdown in the toolbar | + +Run notebook cells in order when the notebook depends on previous variables, imports, or setup steps. + +## Use The File Browser + +The file browser on the left side lets you open, rename, move, upload, and download files. + +Recommended workflow: + +1. Keep active course work in a clear folder. +2. Save assignments and personal results under `/home/jovyan`. +3. Download a backup if the work is important. + +:::{warning} +Some course images use `/ryzers/notebooks` as the default working directory. Move important files to `/home/jovyan` before the environment stops. +::: + +## Use The Terminal + +JupyterLab includes a terminal for shell commands. + +1. Open the Launcher page. +2. Click **Terminal**. +3. Run commands as needed. + +Useful examples: + +```bash +# Check the current directory +pwd + +# List files +ls + +# Copy important work to persistent storage +cp /home/jovyan/ + +# Check GPU status in GPU environments +rocm-smi +``` + +## Save And Exit + +Before leaving JupyterLab: + +1. Save all notebooks. +2. Copy important files to `/home/jovyan`. +3. Shut down long-running notebooks or terminal commands that you no longer need. +4. Return to the Hub control page and click **Stop my server**. + +## Troubleshooting + +### A notebook cell fails + +Check for common issues first: + +- Missing imports +- Typing mistakes +- Cells run out of order +- Missing files or wrong file paths +- Dependencies that were not installed + +### The notebook appears stuck + +- Check whether a cell is still running. +- Interrupt the kernel if needed. +- Restart the kernel if the session is in a bad state. +- Save important files before stopping the server. + +### A file is missing after restart + +Check `/home/jovyan` first. Files that were only kept in temporary directories or default image directories may not persist. diff --git a/source/user-guide/platform-basics.md b/source/user-guide/platform-basics.md new file mode 100644 index 00000000..ac422f19 --- /dev/null +++ b/source/user-guide/platform-basics.md @@ -0,0 +1,147 @@ +# Platform Basics + +This guide covers the basic AUP Learning Cloud workflow: signing in, choosing an environment, understanding storage, and stopping your server when you are done. + +For environment-specific usage, see [JupyterLab Guide](jupyterlab-guide.md) and [Code Server Guide](code-server-guide.md). + +## What AUP Learning Cloud Provides + +AUP Learning Cloud is a browser-based remote learning and development platform. You can use course environments, notebooks, terminals, GPU-enabled runtimes, and browser-based IDE sessions without configuring the full software stack on your local computer. + +You need: + +- A computer with network access +- A modern browser such as Chrome, Edge, or Firefox +- A GitHub-authorized account or a local platform account + +## Open The Platform + +Open the platform URL in your browser: + +```text +https://www.openhw.io/ +``` + +![Platform login page](../_static/images/user-guide/platform-login-page.png) + +## Sign In + +The platform can provide two login methods. Your administrator will tell you which one to use. + +| Login method | When to use it | +|---|---| +| GitHub login | Recommended when your GitHub account has been authorized for the course or lab. | +| Local account login | Use this when an administrator has created a username and password for you. | + +### GitHub Login + +1. Click **Use GitHub Login**. +2. The browser redirects to GitHub. +3. Select the authorized GitHub account. +4. Approve the authorization request. +5. After authorization, the browser returns to AUP Learning Cloud. + +![GitHub login](../_static/images/user-guide/github-login.png) + +### Local Account Login + +If you need a local account, ask the administrator for access. The administrator will provide your username and initial password. + +1. Enter your username and password on the login page. +2. Click **Use LocalAccount Login**. +3. If prompted, change your initial password before continuing. + +If you forget your local account password, contact the administrator. + +## Choose An Environment + +After login, the platform shows a resource selection page. The exact list depends on your course, account permissions, and available hardware. + +![Resource selection page](../_static/images/user-guide/resource-selection-page.png) + +Common resource categories include: + +| Category | Examples | Typical use | +|---|---|---| +| Course | Computer Vision, Deep Learning, Large Language Models, HIP Programming, Genesis Physical Simulation | Course notebooks and lab materials | +| Development | Code Server CPU Environment, Code Server GPU Environment | General coding, IDE workflow, terminal tasks | +| Test | HIP and ROCm Notebook Test | Environment validation and quick tests | +| Tutorial | Introduction to HIP | Guided tutorial content | +| Custom Repo | Basic Python Environment, Basic GPU Environment | Custom repository or base-image work | + +## Launch A Server + +1. Select the environment you want to use. +2. Select hardware resources, such as CPU or GPU, if options are shown. +3. Choose the runtime duration. +4. Click **Launch Server**. +5. Wait for the server to start. +6. The browser opens the selected interface, such as JupyterLab or Code Server. + +![Launch server](../_static/images/user-guide/launch-server.png) + +:::{important} +When the runtime duration expires, the platform may stop the server. Files that are not saved in the persistent user directory can be lost. +::: + +## Save Important Files + +Pay close attention to where your files are stored. + +| Path | Purpose | +|---|---| +| `/ryzers/notebooks` | Default working directory in many images. It is useful for course materials, but content may be reset when the environment stops or changes. | +| `/home/jovyan` | Persistent user directory. Save important work, assignments, notebooks, and results here. | + +If you created files in the default working directory and want to keep them, copy them to `/home/jovyan` before stopping the server: + +```bash +bash +cp /home/jovyan/ +``` + +:::{warning} +Do not rely on the default working directory for important work. Use `/home/jovyan` for files you need after the current session ends. +::: + +## Stop Your Server + +When you finish working, stop your server to release shared resources. + +1. Save your notebooks, code, and output files. +2. Confirm important files are in `/home/jovyan`. +3. Return to the JupyterHub control page. +4. Click **Stop my server**. +5. Wait until the server has stopped before closing the browser tab. + +![Stop my server](../_static/images/user-guide/stop-my-server.png) + +:::{important} +Closing the browser tab or logging out does not always stop the remote server. Use **Stop my server** when you are done. +::: + +## Common Issues + +### The page does not open or loads slowly + +- Check your network connection. +- Refresh the page. +- Try Chrome, Edge, or Firefox. +- Contact the administrator if the platform is still unavailable. + +### I already started one environment and want to switch + +Stop the current server first by clicking **Stop my server**. Then return to the resource selection page and launch the new environment. + +### My files disappeared after restart + +Check whether the files were saved under `/home/jovyan`. Files kept only in a temporary or image-provided working directory may be reset after a server stop, timeout, or image change. + +## Good Practices + +- Save work frequently. +- Keep important files in `/home/jovyan`. +- Use clear file names instead of generic names such as `test.ipynb`. +- Split large experiments into separate notebooks or scripts. +- Stop your server when you are not using it. +- When asking for help, include the environment name, error message, and steps you tried.