Web IDE terminal documentation

b69d7d96 · Francisco Javier López · Marcia Ramos · 46ba8b07 · b69d7d96 · b69d7d96
Commit b69d7d96 authored Dec 11, 2018 by Francisco Javier López Committed by Marcia Ramos Dec 11, 2018
3 changed files
--- a/doc/ci/interactive_web_terminal/index.md
+++ b/doc/ci/interactive_web_terminal/index.md
-# Getting started with interactive web terminals **[CORE ONLY]**
+# Interactive Web Terminals **[CORE ONLY]**

 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/50144) in GitLab 11.3.

@@ -15,7 +15,7 @@ progress.
 Two things need to be configured for the interactive web terminal to work:

 - The Runner needs to have [`[session_server]` configured
-  properly][session-server]
+  properly](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section)
 - If you are using a reverse proxy with your GitLab instance, web terminals need to be
  [enabled](../../administration/integration/terminal.md#enabling-and-disabling-terminal-support)

@@ -45,9 +45,12 @@ the terminal and type commands like a normal shell.

 If you have the terminal open and the job has finished with its tasks, the
 terminal will block the job from finishing for the duration configured in
-[`[session_server].terminal_max_retention_time`][session-server] until you
+[`[session_server].terminal_max_retention_time`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section) until you
 close the terminal window.

 ![finished job with terminal open](img/finished_job_with_terminal_open.png)

-[session-server]: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section
+## Interactive Terminals for the Web IDE **[ULTIMATE]**
+
+Read the Web IDE docs to learn how to run [Interactive Terminals through the Web IDE](../../user/project/web_ide/index.md).
+
--- a/doc/user/permissions.md
+++ b/doc/user/permissions.md
@@ -79,6 +79,7 @@ The following table depicts the various user permission levels in a project.
 | Use security dashboard **[ULTIMATE]** |         |            | ✓           | ✓        | ✓      |
 | Dismiss vulnerability **[ULTIMATE]**  |         |            | ✓           | ✓        | ✓      |
 | Use environment terminals             |         |            |             | ✓        | ✓      |
+| Run Web IDE's Interactive Terminals **[ULTIMATE]** | |       |             | ✓        | ✓      |
 | Add new team members                  |         |            |             | ✓        | ✓      |
 | Push to protected branches            |         |            |             | ✓        | ✓      |
 | Enable/disable branch protection      |         |            |             | ✓        | ✓      |

--- a/doc/user/project/web_ide/index.md
+++ b/doc/user/project/web_ide/index.md
 # Web IDE

-> [Introduced in](https://gitlab.com/gitlab-org/gitlab-ee/issues/4539) [GitLab Ultimate][ee] 10.4.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4539) in [GitLab Ultimate][ee] 10.4.
 > [Brought to GitLab Core](https://gitlab.com/gitlab-org/gitlab-ce/issues/44157) in 10.7.

 The Web IDE editor makes it faster and easier to contribute changes to your
@@ -15,14 +15,14 @@ and from merge requests.

 ## File finder

-> [Introduced in](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18323) [GitLab Core][ce] 10.8.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18323) in [GitLab Core][ce] 10.8.

 The file finder allows you to quickly open files in the current branch by
 searching. The file finder is launched using the keyboard shortcut `Command-p`,
 `Control-p`, or `t` (when editor is not in focus). Type the filename or
 file path fragments to start seeing results.

-## Syntax highligting
+## Syntax highlighting

 As expected from an IDE, syntax highlighting for many languages within 
 the Web IDE will make your direct editing even easier.
@@ -47,7 +47,7 @@ Single file editing is based on the [Ace Editor](https://ace.c9.io).

 After making your changes, click the Commit button in the bottom left to
 review the list of changed files. Click on each file to review the changes and
-click the tick icon to stage the file. 
+click the tick icon to stage the file.

 Once you have staged some changes, you can add a commit message and commit the
 staged changes. Unstaged changes will not be commited.
@@ -65,7 +65,7 @@ shows you a preview of the merge request diff if you commit your changes.

 ## View CI job logs

-> [Introduced in](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19279) [GitLab Core][ce] 11.0.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19279) in [GitLab Core][ce] 11.0.

 The Web IDE can be used to quickly fix failing tests by opening the branch or
 merge request in the Web IDE and opening the logs of the failed job. The status
@@ -77,25 +77,25 @@ left.

 ## Switching merge requests

-> [Introduced in](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19318) [GitLab Core][ce] 11.0.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19318) in [GitLab Core][ce] 11.0.

 Switching between your authored and assigned merge requests can be done without
-leaving the Web IDE. Click the dropdown in the top of the sidebar to open a list 
+leaving the Web IDE. Click the dropdown in the top of the sidebar to open a list
 of merge requests. You will need to commit or discard all your changes before
 switching to a different merge request.

 ## Switching branches

-> [Introduced in](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/20850) [GitLab Core][ce] 11.2.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/20850) in [GitLab Core][ce] 11.2.

 Switching between branches of the current project repository can be done without
-leaving the Web IDE. Click the dropdown in the top of the sidebar to open a list 
+leaving the Web IDE. Click the dropdown in the top of the sidebar to open a list
 of branches. You will need to commit or discard all your changes before
 switching to a different branch.

 ## Client Side Evaluation

-> [Introduced in](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19764) [GitLab Core][ce] 11.2.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19764) in [GitLab Core][ce] 11.2.

 The Web IDE can be used to preview JavaScript projects right in the browser.
 This feature uses CodeSandbox to compile and bundle the JavaScript used to
@@ -128,5 +128,121 @@ IDE. An example `package.json` is below.
 }
 ```

+## Interactive Terminals for the Web IDE **[ULTIMATE]**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5426) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6.
+
+[Interactive terminals](../../../ci/interactive_web_terminal/index.md)
+give the user access to a terminal to interact with the Runner directly from the GitLab
+UI. These terminals can be also accessed via Web IDE.
+
+Only project [**maintainers**](../../permissions.md#project-members-permissions)
+can run Interactive Terminals through the Web IDE.
+
+### Runner configuration
+
+Web IDE Interactive Terminals are not supported by Shared Runners.
+To make use of this feature, you need to provide your
+[own Runner](https://docs.gitlab.com/runner/install/) and properly
+[configure it](#configuration).
+
+Some things need to be configured in the runner for the interactive web terminal
+to work:
+
+- The Runner needs to have 
+  [`[session_server]` configured properly](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section).
+- If you are using a reverse proxy with your GitLab instance, web terminals need to be
+  [enabled](../../../administration/integration/terminal.md#enabling-and-disabling-terminal-support). **[ULTIMATE ONLY]**
+
+If you have the terminal open and the job has finished with its tasks, the
+terminal will block the job from finishing for the duration configured in
+[`[session_server].terminal_max_retention_time`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section)
+until you close the terminal window.
+
+NOTE: **Note:** Not all executors are
+[supported](https://docs.gitlab.com/runner/executors/#compatibility-chart)
+
+### Web IDE configuration file
+
+In order to enable the Web IDE terminals you need to create the file
+`.gitlab/.gitlab-webide.yml` inside the repository's root. This
+file is fairly similar to the [CI configuration file](../../../ci/yaml/README.md)
+syntax but with some restrictions:
+
+- No global blocks can be defined (ie: `before_script` or `after_script`)
+- Only one job named `terminal` can be added to this file.
+- Only the keywords `image`, `services`, `tags`, `before_script`, `script`, and
+`variables` are allowed to be used to configure the job.
+- To connect to the interactive terminal, the `terminal` job must be still alive
+and running, otherwise the terminal won't be able to connect to the job's session.
+By default the `script` keyword has the value `sleep 60` to prevent
+the job from ending and giving the Web IDE enough time to connect. This means
+that, if you override the default `script` value, you'll have to add a command
+which would keep the job running, like `sleep`.
+
+In the code below there is an example of this configuration file:
+
+```yaml
+terminal:
+  before_script:
+    - apt-get update
+  script: sleep 60
+  variables:
+    RAILS_ENV: "test"
+    NODE_ENV: "test"
+```
+
+Once the terminal has started, the console will be displayed and we could access
+the project repository files.
+
+**Important**. The terminal job is branch dependant. This means that the
+configuration file used to trigger and configure the terminal will be the one in
+the selected branch of the Web IDE.
+
+If there is no configuration file in a branch, an error message will be shown.
+
+### Running Interactive Terminals in the Web IDE
+
+If Interactive Terminals are available for the current user, the **Terminal** button
+will be visible in the right sidebar of the Web IDE. Click this button to open
+or close the terminal tab.
+
+Once open, the tab will show the **Start Web Terminal** button. This button may
+be disabled if the environment is not configured correctly. If so, a status
+message will describe the issue. Here are some reasons why **Start Web Terminal** 
+may be disabled:
+
+- `.gitlab/.gitlab-webide.yml` does not exist or is set up incorrectly.
+- No active private runners are available for the project.
+
+If active, clicking the **Start Web Terminal** button will load the terminal view
+and start connecting to the runner's terminal. At any time, the **Terminal** tab
+can be closed and reopened and the state of the terminal will not be affected.
+
+When the terminal is started and is successfully connected to the runner, then the
+runner's shell prompt will appear in the terminal. From here, you can enter
+commands that will be executed within the runner's environment. This is similar
+to running commands in a local terminal or through SSH.
+
+While the terminal is running, it can be stopped by clicking **Stop Terminal**.
+This will disconnect the terminal and stop the runner's terminal job. From here,
+click **Restart Terminal** to start a new terminal session.
+
+### Limitations
+
+Interactive Terminals is in a beta phase and will continue to be improved upon in upcoming 
+releases. In the meantime, please note that the user is limited to having only one
+active terminal at a time.
+
+### Troubleshooting
+
+- If the terminal's text is gray and unresponsive, then the terminal has stopped
+  and it can no longer be used. A stopped terminal can be restarted by clicking
+  **Restart Terminal**.
+- If the terminal displays **Connection Failure**, then the terminal could not
+  connect to the runner. Please try to stop and restart the terminal. If the
+  problem persists, double check your runner configuration.
+
+
 [ce]: https://about.gitlab.com/pricing/
 [ee]: https://about.gitlab.com/pricing/