Code server
Contents
VS Code (Web) Tutorial - KENET HPC Cluster
Overview
VS Code is a powerful, modern code editor that runs in your web browser, providing a full development environment with syntax highlighting, debugging, Git integration, and extensions. It offers the complete VS Code experience without requiring any local installation, making it ideal for cloud-based development on the KENET HPC cluster.
Use Cases: VS Code is particularly well-suited for Python, R, and Julia development with data analysis workflows, editing configuration files and scripts directly on the cluster, interactive debugging with breakpoints and variable inspection, Git version control for research code management, Jupyter notebook development within the editor, and multi-language project development with a single interface.
Access: VS Code is available through the KENET Open OnDemand web portal at https://ondemand.vlab.ac.ke
Code Examples: All code examples for this tutorial are available in our GitHub repository at https://github.com/Materials-Modelling-Group/training-examples
Prerequisites
Before using VS Code, you should have an active KENET HPC cluster account with access to the Open OnDemand portal. Basic familiarity with a programming language such as Python, R, or shell scripting will be helpful. Your project files should be stored in your home directory at /home/username/localscratch
Launching VS Code
Step 1: Access Interactive Apps
Begin by logging into Open OnDemand at https://ondemand.vlab.ac.ke using your KENET credentials. Once logged in, click the Interactive Apps menu in the top navigation bar, then select VS Code from the dropdown list of available applications.
Step 2: Configure Job Parameters
The job submission form allows you to specify the computational resources needed for your VS Code session. For most development work, modest resources are sufficient since you are primarily editing code rather than running intensive computations.
| Parameter | Description | Recommended Value |
|---|---|---|
| Partition | Queue for job execution | normal for general development
|
| Walltime | Maximum runtime in hours | 4 hours for development sessions
|
| CPU Cores | Number of processor cores | 2-4 cores for typical work
|
| Memory | RAM allocation | 8 GB is sufficient for most tasks
|
| Working Directory | Starting directory | /home/username or your project folder
|
Tip: VS Code itself is lightweight, so you typically do not need large resource allocations unless you plan to run computational tasks from the integrated terminal.
Step 3: Submit and Wait
After configuring your job parameters, click the Launch button to submit your job to the cluster scheduler. The job will initially show a "Queued" status while waiting for resources to become available. Once resources are allocated (typically within 30-60 seconds), the status will change to "Running" and a Connect to VS Code button will appear. Click this button to open your VS Code session in a new browser tab.
Quick Start Guide
Understanding the VS Code Interface
When VS Code opens, you will see a clean interface divided into several key areas. The Activity Bar on the far left provides access to different views such as Explorer, Search, Source Control, and Extensions. The Side Bar displays the content of the selected view. The Editor area in the center is where you write and edit your code. The Panel at the bottom can show the integrated terminal, problems, output, and debug console.
Opening Files and Folders
To begin working with your files, click File -> Open Folder from the menu. Navigate to your home directory or project folder at /home/username/localscratch and click OK to open the workspace. The Explorer view in the Side Bar will now display your project structure, allowing you to browse and open files with a single click.
Creating Your First Python File
To create a new Python file, right-click in the Explorer view and select New File, then name it with a .py extension. See the examples/01_hello_cluster.py file in our GitHub repository for a simple example to get started. Type or paste the code into the editor and save with Ctrl+S.
Running Code
There are multiple ways to execute your code in VS Code. You can use the integrated terminal by pressing Ctrl+` (backtick) to open it, then type commands like python script.py to run your code. Alternatively, if you have the Python extension installed, you can right-click in the editor and select "Run Python File in Terminal" for a more streamlined experience.
Installing Extensions
Extensions significantly enhance VS Code's capabilities. To browse and install extensions, click the Extensions icon in the Activity Bar (it looks like four squares with one detached) or press Ctrl+Shift+X.
Essential Extensions
The Python extension by Microsoft provides comprehensive Python language support including IntelliSense code completion, linting, debugging, and Jupyter notebook integration. Search for "Python" in the extensions marketplace and click Install.
The Jupyter extension enables you to create and run Jupyter notebooks directly within VS Code, combining the power of notebooks with the full editor experience. This is particularly useful for data science workflows.
The GitLens extension enhances Git capabilities by showing code authorship, commit history inline, and providing powerful repository visualization tools. This helps you understand how your code has evolved over time.
The Remote - SSH extension allows you to connect to other systems, though this is less relevant when you are already working on the cluster through Open OnDemand.
See extensions/recommended_extensions.md in our GitHub repository for a complete list of useful extensions for HPC development.
Common Tasks
Task 1: Working with the Integrated Terminal
The integrated terminal in VS Code provides full access to the cluster's command line environment. Press Ctrl+` to open it, or go to Terminal → New Terminal from the menu. The terminal opens in your working directory and has access to all loaded environment modules. See the examples/02_terminal_usage.sh file for examples of common terminal commands you will use frequently.
You can open multiple terminal instances by clicking the plus icon in the terminal panel. This is useful when you want to run a long computation in one terminal while keeping another available for quick commands. Split terminals are also available by clicking the split icon.
Task 2: Git Version Control
VS Code provides excellent Git integration for managing your code versions. To initialize a Git repository, open the Source Control view from the Activity Bar (the branch icon) and click Initialize Repository. This creates a new Git repository in your current workspace folder.
The Source Control view shows all modified files. To commit changes, stage the files you want to include by clicking the plus icon next to each file, enter a commit message in the text box at the top, and click the checkmark to commit. See examples/03_git_workflow.sh in our GitHub repository for a complete workflow including connecting to remote repositories.
Task 3: Python Development and Debugging
VS Code offers powerful debugging capabilities for Python code. To debug a script, open your Python file and click in the left margin next to line numbers to set breakpoints (red dots will appear). Press F5 or go to Run → Start Debugging to begin a debug session. The code will run until it hits a breakpoint, then you can inspect variables, step through code line by line, and evaluate expressions.
The Debug Console allows you to execute Python code in the context of your paused program. The Variables pane shows all local and global variables with their current values. See examples/04_debugging_example.py for a sample script with common debugging scenarios.
Task 4: Working with Jupyter Notebooks
After installing the Jupyter extension, you can create and run notebooks directly in VS Code. Create a new file with a .ipynb extension, and VS Code will open it in notebook mode. Click the plus icon to add cells, and use the play button or Shift+Enter to execute cells.
The advantage of using notebooks in VS Code is that you get the full editor features including IntelliSense, debugging, and Git integration while maintaining the interactive cell-based workflow. See examples/05_notebook_in_vscode.ipynb for an example notebook demonstrating data analysis workflows.
Task 5: Multi-file Project Development
For larger projects with multiple files, VS Code provides excellent navigation and refactoring tools. Use Ctrl+P to quickly open files by name. Use F12 to jump to function or class definitions across files. Use Shift+F12 to find all references to a function or variable throughout your project.
The projects/data_pipeline/ directory in our GitHub repository demonstrates a multi-file Python project structure with proper organization, imports, and configuration files.
Tips & Best Practices
Performance Optimization
For optimal performance, request 2-4 cores for typical development work. Close unused editor tabs to keep the interface responsive. Use the search functionality sparingly on large directories, as it can be resource-intensive. Save your work frequently using Ctrl+S, though VS Code does provide auto-save which you can enable in File → Auto Save.
Keyboard Shortcuts
Learning keyboard shortcuts significantly improves productivity. Press Ctrl+Shift+P to open the Command Palette, which provides access to all VS Code commands through a searchable interface. Use Ctrl+B to toggle the Side Bar visibility for more editor space. Press Ctrl+` to toggle the terminal. Use Ctrl+/ to comment or uncomment lines of code. Press Alt+Up or Alt+Down to move lines up or down.
Session Management
VS Code sessions run for the duration of your requested walltime. Your workspace state including open files, editor layout, and terminal sessions persists as long as the session is running. If you close the browser tab, you can reconnect by clicking the Connect to VS Code button again on the session card. However, once the walltime expires, the session terminates and unsaved work will be lost.
Security Best Practices
Never commit credentials or API keys to Git repositories. Use a .gitignore file to exclude sensitive configuration files from version control. Keep API keys in environment variables or in configuration files that are explicitly excluded from Git. The examples/06_security_patterns.py file demonstrates secure ways to handle credentials.
Example Workflows
Example 1: Data Analysis Script Development
Objective: Develop and test a Python script for data processing with proper error handling and logging.
Begin by launching VS Code with 4 cores and a 4-hour walltime. Open your project directory containing your data files. Create a new Python file and follow the structure shown in workflows/01_data_analysis_script.py from our GitHub repository.
The workflow demonstrates loading data from CSV files, implementing error handling with try-except blocks, adding logging to track execution progress, processing data with pandas, generating visualizations, and exporting results. Use the integrated terminal to test your script with sample data before running it on the full dataset. The debugger helps identify and fix issues quickly when they arise.
Example 2: Version Controlled Research Project
Objective: Create a research analysis project with Git version control for reproducibility and collaboration.
Launch VS Code and open your project folder. Initialize a Git repository using the Source Control view. Follow the project structure shown in workflows/02_research_project/ which includes a README file documenting the project, Python scripts organized by function, a requirements file listing dependencies, a data directory (excluded from Git), a results directory for outputs, and a proper .gitignore file.
Make regular commits as you develop your analysis. Push changes to a remote repository on GitHub or GitLab for backup and collaboration. The workflow demonstrates how to create meaningful commit messages, work with branches for experimental features, and merge changes back into the main branch.
Example 3: Machine Learning Development
Objective: Develop and iterate on machine learning models with organized code structure and experiment tracking.
Launch VS Code with the GPU partition if you need GPU acceleration. The workflows/03_ml_development/ directory demonstrates a complete ML project structure including data preprocessing modules, model definition files, training scripts with hyperparameter configuration, evaluation and visualization code, and notebooks for exploration.
Use VS Code's debugging capabilities to step through model training and inspect tensor shapes and values. The integrated terminal allows you to run training jobs while you continue editing code. Use Git to track different model architectures and hyperparameter configurations.
Troubleshooting
Problem: Extensions won't install
Extension installation failures typically occur due to network issues or permissions problems. First, try closing and reopening VS Code. Check that you have write access to your home directory with the command ls -la ~ in the terminal. If the problem persists, some extensions may not be compatible with the web version of VS Code. Consider using alternative extensions with similar functionality.
Problem: Terminal not opening or freezing
If the integrated terminal fails to open or becomes unresponsive, first try closing the terminal panel and opening a new one with Ctrl+`. If that does not work, check the cluster status to ensure the compute node is responsive. As a last resort, disconnect from the session and reconnect using the Connect to VS Code button. If problems continue, contact KENET support as there may be an issue with the compute node.
Problem: Cannot access files or folders
File access problems usually indicate permission issues or incorrect paths. Verify the path by running pwd in the terminal to see your current directory. Check file permissions with ls -la /path/to/file. Ensure you are trying to access files within your home directory or areas where you have been granted access. You cannot access files in other users' home directories without explicit permission.
Problem: Git authentication failing
When pushing to remote repositories, you may encounter authentication failures. GitHub no longer accepts password authentication, so you must use a personal access token or SSH keys. See examples/03_git_workflow.sh for instructions on setting up SSH keys for Git authentication. Alternatively, use HTTPS with a personal access token stored securely.
Problem: Python interpreter not found
If the Python extension cannot find the Python interpreter, you need to select it manually. Press Ctrl+Shift+P to open the Command Palette, type "Python: Select Interpreter", and choose from the available Python installations. The cluster modules you loaded before launching VS Code should be available. If not, you can load modules in the integrated terminal with module load commands.
Additional Resources
The official VS Code documentation is available at https://code.visualstudio.com/docs and provides comprehensive information about all features and capabilities. The Python in VS Code guide at https://code.visualstudio.com/docs/python/python-tutorial is particularly useful for data science workflows. KENET HPC usage guidelines are documented at https://training.kenet.or.ke/index.php/HPC_Usage.
For learning VS Code effectively, Microsoft provides interactive tutorials at https://code.visualstudio.com/learn and video courses at https://learn.microsoft.com/en-us/shows/intro-to-vs-code/. The VS Code tips and tricks page at https://code.visualstudio.com/docs/getstarted/tips-and-tricks contains many productivity-enhancing shortcuts and features.
Code Examples Repository: All code examples referenced in this tutorial are available at https://github.com/Materials-Modelling-Group/training-examples
For support, contact KENET at support@kenet.or.ke, consult the documentation at https://training.kenet.or.ke, or access the Open OnDemand portal at https://ondemand.vlab.ac.ke.
Feedback
If you encounter issues or have suggestions for improving this tutorial, please contact KENET support or submit feedback through the Open OnDemand interface using the feedback button.
