diff --git a/docs/img/apps_ssh_session_dashboard.png b/docs/img/apps_ssh_session_dashboard.png new file mode 100644 index 00000000..3efde152 Binary files /dev/null and b/docs/img/apps_ssh_session_dashboard.png differ diff --git a/docs/img/apps_ssh_session_wizard.png b/docs/img/apps_ssh_session_wizard.png new file mode 100644 index 00000000..5648fa78 Binary files /dev/null and b/docs/img/apps_ssh_session_wizard.png differ diff --git a/docs/webapp/applications/apps_overview.md b/docs/webapp/applications/apps_overview.md index 7522a0e2..de26f8d8 100644 --- a/docs/webapp/applications/apps_overview.md +++ b/docs/webapp/applications/apps_overview.md @@ -20,6 +20,8 @@ ClearML provides the following applications: * [**Task Scheduler**](apps_task_scheduler.md) - Schedule tasks for one-shot and/or periodic execution at specified times (available under ClearML Enterprise Plan) * [**Trigger Manager**](apps_trigger_manager.md) - Define tasks to be run when predefined events occur (available under ClearML Enterprise Plan) * **AI Dev**: Applications for deploying AI development environments on remote machines. + * [**SSH Session**](apps_ssh_session.md) - Launch a full development environment on a remote machine with a + detached interactive SSH session (available under ClearML Enterprise Plan) * [**Jupyter Lab**](apps_jupyter_lab.md) - Launch a Jupyter Lab session on a remote machine (available under ClearML Enterprise Plan) * [**VS Code**](apps_vscode.md) - Launch a VS Code session on a remote machine (available under ClearML Enterprise Plan) * **UI Dev**: Applications for deploying user interfaces for models. diff --git a/docs/webapp/applications/apps_ssh_session.md b/docs/webapp/applications/apps_ssh_session.md new file mode 100644 index 00000000..44b3ccf4 --- /dev/null +++ b/docs/webapp/applications/apps_ssh_session.md @@ -0,0 +1,95 @@ +--- +title: SSH Session +--- + +:::important Enterprise Feature +The SSH Session application is available under the ClearML Enterprise plan. +::: + +The SSH Session UI application allows you to launch a full development environment on a remote machine complete with +a detached interactive SSH session. + +The Session app offers workspace management features, allowing you to store, sync, and restore interactive workspaces +across sessions. This ensures that all your work is preserved and can be easily accessed in future sessions. + +The SSH Session is set up using a [ClearML Agent](../../clearml_agent.md). When configuring an app instance, select a +queue, and the agent servicing that queue will set up the remote environment and SSH session. When the environment setup is +complete, the app instance dashboard displays SSH connection parameters and the command line to connect to the session. + +The application monitors the session's activity and shuts down if it is inactive for a specified maximum idle time. + +Once you have launched an app instance, you can view the following information in its dashboard: + +* App status indicator + * Active instance - Remote SSH session is setting up + * Loading instance - Remote SSH session is active + * Idle instance - Remote SSH session is idle + * Stopped instance - Remote SSH session is stopped +* Idle time +* Restored workspace - If a previous session’s workspace was restored, this will display its session ID +* Current session ID +* SSH:Host:Port - The hostname and port for the SSH connection +* User - SSH username for the interactive session +* Password - SSH password for the interactive session +* Connect Command - The command line to initiate an SSH connection to the remote environment +* Remote environment's resource metrics over time: + * CPU usage + * Network throughput + * Disk performance + * Memory performance + * GPU utilization + * GPU memory usage +* Console - The console log shows the instance's activity, including session setup progress and SSH server status changes + +![SSH Session Dashboard](../../img/apps_ssh_session_dashboard.png) + +## SSH Session Instance Configuration + +When configuring a new SSH Session instance, you can fill in the required parameters or reuse the configuration of +a previously launched instance. + +Launch an app instance with the configuration of a previously launched instance using one of the following options: +* Cloning a previously launched app instance will open the instance launch form with the original instance's +configuration prefilled. +* Importing an app configuration file. You can export the configuration of a previously launched instance as a JSON file +when viewing its configuration. + +The prefilled instance launch form can be edited before starting the new app instance. + +To configure a new app instance, click `Launch New` Add new +to open the app's instance launch form. + + +### Configuration Options +* Import Configuration - Import an app instance configuration file. This will fill the instance launch form with the +values from the file, which can be modified before launching the app instance +* Git - The details for a git repository to optionally clone into your remote environment: + * Repository + * Branch + * Commit +* Docker - Input details to run the session in Docker container + * Image - Docker image to launch + * Docker Arguments - Additional arguments for the Docker image + * Init Script - Bash script that is executed upon container boot (comments are supported only at the beginning of the + line) +* Extra Packages - Specify Python packages to install when setting up the remote environment +* Persistent Workspace Path - Specify your workspace root directory, it will be automatically stored when the session is +closed and restored into a new instance when the session app instance is cloned (example: `~/workspace`) +* Queue - The [ClearML Queue](../../fundamentals/agents_and_queues.md#what-is-a-queue) to which the SSH Session app + instance task will be enqueued (make sure an agent is assigned to that queue) +* Maximum idle time (in hours) - Maximum idle time after which the app instance will shut down +* Interactive Session Name - Name your current interactive session +* Advanced Options + * Interactive Session Project - The project in which the interactive session is created. If left empty, the default + project `Interactive Session` is used + * Interactive Session Tags - Comma separated list of tags to add to your interactive session + * Restore Interactive Workspace ID - Input a previously run interactive session ID to restore its workspace + * Use DropBear SSH server instead of OpenSSH server - Use DropBear SSH server instead of OpenSSH server. Required if + not running as root inside container + * Idle Network Threshold (MB) - Network throughput under which the session will be considered idle + * Idle CPU Threshold (%) - CPU utilization under which the session will be considered idle + * Idle GPU Threshold (%) - GPU utilization under which the session will be considered idle +* Export Configuration - Export the app instance configuration as a JSON file, which you can later import to create a +new instance with the same configuration + +![SSH Session form](../../img/apps_ssh_session_wizard.png) \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index f62c0d4b..7538a25b 100644 --- a/sidebars.js +++ b/sidebars.js @@ -157,6 +157,7 @@ module.exports = { }, { "AI Dev": [ + 'webapp/applications/apps_ssh_session', 'webapp/applications/apps_jupyter_lab', 'webapp/applications/apps_vscode', ] diff --git a/static/icons/ico-ssh-active.svg b/static/icons/ico-ssh-active.svg new file mode 100644 index 00000000..cdb1e7ec --- /dev/null +++ b/static/icons/ico-ssh-active.svg @@ -0,0 +1,15 @@ + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/static/icons/ico-ssh-idle.svg b/static/icons/ico-ssh-idle.svg new file mode 100644 index 00000000..aaa6b2e8 --- /dev/null +++ b/static/icons/ico-ssh-idle.svg @@ -0,0 +1,15 @@ + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/static/icons/ico-ssh-loading.svg b/static/icons/ico-ssh-loading.svg new file mode 100644 index 00000000..7c96e1a5 --- /dev/null +++ b/static/icons/ico-ssh-loading.svg @@ -0,0 +1,32 @@ + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/static/icons/ico-ssh-stopped.svg b/static/icons/ico-ssh-stopped.svg new file mode 100644 index 00000000..dee68561 --- /dev/null +++ b/static/icons/ico-ssh-stopped.svg @@ -0,0 +1,15 @@ + + + + + + + + + + + + + + +