Merge branch 'docs-repo-merge-28-project-ops' into 'master'

Docs: Merge 4 EE doc/user/project dirs to CE

See merge request gitlab-org/gitlab-ce!27982

doc/user/project/operations/feature_flags.md

+# Feature Flags **[PREMIUM]**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845) in GitLab 11.4.
+
+CAUTION: **Warning:**
+This an _alpha_ feature and is subject to change at any time without
+prior notice.
+
+Feature flags allow you to ship a project in different flavors by
+dynamically toggling certain functionality.
+
+## Overview
+
+Feature Flags offer a feature toggle system for your application. They enable teams
+to achieve Continuous Delivery by deploying new features to production at smaller
+batches for controlled testing, separating feature delivery from customer launch.
+This helps reducing risk and allows you to easily manage which features to enable.
+
+GitLab offers a Feature Flags interface that allows you to create, toggle and
+remove feature flags.
+
+## How it works
+
+Underneath, GitLab uses [unleash](https://github.com/Unleash/unleash), a feature
+toggle service. GitLab provides an API where your application can talk to and get the
+list of feature flags you set in GitLab.
+
+The application must be configured to talk to GitLab, so that's up to the
+developers to use a compatible [client library](#client-libraries) and
+integrate it in their app.
+
+By setting a flag active or inactive via GitLab, your application will automatically
+know which features to enable or disable respectively.
+
+## Adding a new feature flag
+
+To add a new feature flag:
+
+1. Navigate to your project's **Operations > Feature Flags**.
+1. Click on the **New Feature Flag** button.
+1. Give it a name.
+
+    NOTE: **Note:**
+    A name can contain only lowercase letters, digits, underscores (`_`)
+    and dashes (`-`), must start with a letter, and cannot end with a dash (`-`)
+    or an underscore (`_`).
+
+1. Give it a description (optional, 255 characters max).
+1. Define environment [specs](#define-environment-specs). If you want the flag on by default, enable the catch-all [wildcard spec (`*`)](#define-environment-specs)
+1. Click **Create feature flag**.
+
+Once a feature flag is created, the list of existing feature flags will be presented
+with ability to edit or remove them.
+
+To make a feature flag active or inactive, click the pencil icon to edit it,
+and toggle the status for each [spec](#define-environment-specs).
+
+![Feature flags list](img/feature_flags_list.png)
+
+## Define environment specs
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/8621) in GitLab 11.8.
+
+In general, an application is deployed to multiple environments, such as
+production, staging and [review apps](../../../ci/review_apps/index.md).
+For example, you may not want to enable a feature flag on production until your QA team has
+first confirmed that the feature is working correctly on testing environments.
+
+To handle these situations, you can enable a feature flag on a particular environment
+with [Environment specs](../../../ci/environments.md#scoping-environments-with-specs-premium).
+You can define multiple specs per flag so that you can control your feature flag more granularly.
+
+To define specs for each environment:
+
+1. Navigate to your project's **Operations > Feature Flags**.
+1. Click on the **New Feature Flag** button or edit an existing flag.
+1. Set the status of the default [spec](../../../ci/environments.md#scoping-environments-with-specs-premium) (`*`). This status will be used for _all_ environments.
+1. If you want to enable/disable the feature on a specific environment, create a new [spec](../../../ci/environments.md#scoping-environments-with-specs-premium) and type the environment name.
+1. Set the status of the additional spec. This status takes precedence over the default spec's status since we always use the most specific match available.
+1. Click **Create feature flag** or **Update feature flag**.
+
+![Feature flag specs list](img/specs_list.png)
+
+NOTE: **NOTE**
+We'd highly recommend you to use the [Environment](../../../ci/environments.md)
+feature in order to quickly assess which flag is enabled per environment.
+
+## Integrating with your application
+
+In order to use Feature Flags, you need to first
+[get the access credentials](#configuring-feature-flags) from GitLab and then
+prepare your application and hook it with a [client library](#client-libraries).
+
+### Configuring Feature Flags
+
+To get the access credentials that your application will need to talk to GitLab:
+
+1. Navigate to your project's **Operations > Feature Flags**.
+1. Click on the **Configure** button to see the values:
+    - **API URL**: URL where the client (application) connects to get a list of feature flags.
+    - **Instance ID**: Unique token that authorizes the retrieval of the feature flags.
+    - **Application name**: The name of the running environment. For instance,
+       if the application runs for production server, application name would be
+      `production` or similar. This value is used for
+      [the environment spec evaluation](#define-environment-specs).
+
+NOTE: **Note:**
+The meaning of these fields might change over time. For example, we are not sure
+if **Instance ID** will be single token or multiple tokens, assigned to the
+**Environment**. Also, **Application name** could describe the version of
+application instead of the running environment.
+
+### Client libraries
+
+GitLab currently implements a single backend that is compatible with
+[Unleash](https://github.com/Unleash/unleash#client-implementations) clients.
+
+Unleash clients allow the developers to define in the app's code the default
+values for flags. Each feature flag evaluation can express the desired
+outcome in case the flag isn't present on the provided configuration file.
+
+Unleash currently offers a number of official SDKs for various frameworks and
+a number of community contributed libraries.
+
+Official clients:
+
+- [unleash/unleash-client-java](https://github.com/unleash/unleash-client-java)
+- [unleash/unleash-client-node](https://github.com/unleash/unleash-client-node)
+- [unleash/unleash-client-go](https://github.com/unleash/unleash-client-go)
+- [unleash/unleash-client-ruby](https://github.com/unleash/unleash-client-ruby)
+
+Community contributed clients:
+
+- [stiano/unleash-client-dotnet](https://github.com/stiano/unleash-client-dotnet) (.Net Core)
+- [onybo/unleash-client-core](https://github.com/onybo/unleash-client-core) (.Net Core)
+- [aes/unleash-client-python](https://github.com/aes/unleash-client-python) (Python 3)
+
+### Golang application example
+
+Here's an example of how to integrate the feature flags in a Golang application:
+
+```golang
+package main
+
+import (
+    "io"
+    "log"
+    "net/http"
+
+    "github.com/Unleash/unleash-client-go"
+)
+
+type metricsInterface struct {
+}
+
+func init() {
+    unleash.Initialize(
+        unleash.WithUrl("https://gitlab.com/api/v4/feature_flags/unleash/42"),
+        unleash.WithInstanceId("29QmjsW6KngPR5JNPMWx"),
+        unleash.WithAppName("production"),
+        unleash.WithListener(&metricsInterface{}),
+    )
+}
+
+func helloServer(w http.ResponseWriter, req *http.Request) {
+    if unleash.IsEnabled("my_feature_name") {
+        io.WriteString(w, "Feature enabled\n")
+    } else {
+        io.WriteString(w, "hello, world!\n")
+    }
+}
+
+func main() {
+    http.HandleFunc("/", helloServer)
+    log.Fatal(http.ListenAndServe(":8080", nil))
+}
+```

doc/user/project/operations/index.md

@@ -7,5 +7,5 @@ your applications:
 - Deploy to different [environments](../../../ci/environments.md).
 - Connect your project to a [Kubernetes cluster](../clusters/index.md).
 - Discover and view errors generated by your applications with [Error Tracking](error_tracking.md).
-- Create, toggle, and remove [Feature Flags](https://docs.gitlab.com/ee/user/project/operations/feature_flags.html). **[PREMIUM]**
-- [Trace](https://docs.gitlab.com/ee/user/project/operations/tracing.html) the performance and health of a deployed application. **[ULTIMATE]**
+- Create, toggle, and remove [Feature Flags](feature_flags.md). **[PREMIUM]**
+- [Trace](tracing.md) the performance and health of a deployed application. **[ULTIMATE]**

doc/user/project/operations/tracing.md

+# Tracing **[ULTIMATE]**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/7903) in GitLab Ultimate 11.5.
+
+Tracing provides insight into the performance and health of a deployed application,
+tracking each function or microservice which handles a given request.
+
+This makes it easy to
+understand the end-to-end flow of a request, regardless of whether you are using a monolithic or distributed system.
+
+## Jaeger tracing
+
+[Jaeger](https://www.jaegertracing.io/) is an open source, end-to-end distributed
+tracing system used for monitoring and troubleshooting microservices-based distributed
+systems.
+
+### Deploying Jaeger
+
+To learn more about deploying Jaeger, read the official
+[Getting Started documentation](https://www.jaegertracing.io/docs/latest/getting-started/).
+There is an easy to use [all-in-one Docker image](https://www.jaegertracing.io/docs/latest/getting-started/#AllinoneDockerimage),
+as well as deployment options for [Kubernetes](https://github.com/jaegertracing/jaeger-kubernetes)
+and [OpenShift](https://github.com/jaegertracing/jaeger-openshift).
+
+### Enabling Jaeger
+
+GitLab provides an easy way to open the Jaeger UI from within your project:
+
+1. [Set up Jaeger](#deploying-jaeger) and configure your application using one of the
+   [client libraries](https://www.jaegertracing.io/docs/latest/client-libraries/).
+1. Navigate to your project's **Settings > Operations** and provide the Jaeger URL.
+1. Click **Save changes** for the changes to take effect.
+1. You can now visit **Operations > Tracing** in your project's sidebar and
+   GitLab will redirect you to the configured Jaeger URL.
\ No newline at end of file

doc/user/project/packages/maven.md

+---
+redirect_to: 'maven_repository.md'
+---
+
+This document was moved to [another location](maven_repository.md).

doc/user/project/packages/maven_packages.md

+---
+redirect_to: 'maven_repository.md'
+---
+
+This document was moved to [another location](maven_repository.md).

doc/user/project/packages/npm_registry.md

+# GitLab NPM Registry **[PREMIUM]**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5934)
+  in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7.
+
+With the GitLab NPM Registry, every
+project can have its own space to store NPM packages.
+
+![GitLab NPM Registry](img/npm_package_view.png)
+
+NOTE: **Note:**
+Only [scoped](https://docs.npmjs.com/misc/scope) packages are supported.
+
+
+NOTE: **Note:**
+As `@group/subgroup/project` is not a valid NPM package name, publishing a package 
+within a subgroup is not supported yet. 
+
+## Enabling the NPM Registry
+
+NOTE: **Note:**
+This option is available only if your GitLab administrator has
+[enabled support for the NPM registry](https://docs.gitlab.com/ee/administration/packages.html).**[PREMIUM ONLY]**
+
+After the NPM registry is enabled, it will be available for all new projects
+by default. To enable it for existing projects, or if you want to disable it:
+
+1. Navigate to your project's **Settings > General > Permissions**.
+1. Find the Packages feature and enable or disable it.
+1. Click on **Save changes** for the changes to take effect.
+
+You should then be able to see the **Packages** section on the left sidebar.
+
+Before proceeding to authenticating with the GitLab NPM Registry, you should
+get familiar with the package naming convention.
+
+## Package naming convention
+
+**Only packages that have the same path as the project** are supported. For
+ example:
+
+| Project                | Package                 | Supported |
+| ---------------------- | ----------------------- | --------- |
+| `foo/bar`              | `@foo/bar`              | Yes       |
+| `gitlab-org/gitlab-ce` | `@gitlab-org/gitlab-ce` | Yes       |
+| `gitlab-org/gitlab-ce` | `@foo/bar`              | No        |
+
+Now, you can configure your project to authenticate with the GitLab NPM
+Registry.
+
+## Authenticating to the GitLab NPM Registry
+
+If a project is private or you want to upload an NPM package to GitLab,
+credentials will need to be provided for authentication. Support is available
+only for [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow).
+
+CAUTION: **2FA not supported:**
+Authentication for personal access tokens is not yet supported
+([#9140](https://gitlab.com/gitlab-org/gitlab-ee/issues/9140)). If you have 2FA
+enabled, you won't be able to authenticate to the GitLab NPM Registry.
+
+### Authenticating with an OAuth token
+
+To authenticate with an [OAuth token](../../../api/oauth2.md#resource-owner-password-credentials-flow),
+add a corresponding section to your `.npmrc` file:
+
+```ini
+; Set URL for your scoped packages.
+; For example package with name `@foo/bar` will use this URL for download
+@foo:registry=https://gitlab.com/api/v4/packages/npm/
+
+; Add the OAuth token for the scoped packages URL. This will allow you to download
+; `@foo/` packages from private projects.
+//gitlab.com/api/v4/packages/npm/:_authToken=<your_oauth_token>
+
+; Add OAuth token for uploading to the registry. Replace <your_project_id>
+; with the project you want your package to be uploaded to.
+//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=<your_oauth_token>
+```
+
+Replace `<your_project_id>` with your project ID which can be found on the home page
+of your project and `<your_oauth_token>` with your OAuth token.
+
+If you have a self-hosted GitLab installation, replace `gitlab.com` with your
+domain name.
+
+You should now be able to download and upload NPM packages to your project.
+
+## Uploading packages
+
+Before you will be able to upload a package, you need to specify the registry
+for NPM. To do this, add the following section to the bottom of `package.json`:
+
+```json
+  "publishConfig": {
+    "@foo:registry":"https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/"
+  }
+```
+
+Replace `<your_project_id>` with your project ID, which can be found on the home
+page of your project, and replace `@foo` with your own scope.
+
+If you have a self-hosted GitLab installation, replace `gitlab.com` with your
+domain name.
+
+Once you have enabled it and set up [authentication](#authenticating-to-the-gitlab-npm-registry),
+you can upload an NPM package to your project:
+
+```sh
+npm publish
+```
+
+You can then navigate to your project's **Packages** page and see the uploaded
+packages or even delete them.
+
+## Uploading a package with the same version twice
+
+If you upload a package with a same name and version twice, GitLab will show
+both packages in the UI, but the GitLab NPM Registry will expose the most recent
+one as it supports only one package per version for `npm install`.

doc/user/project/settings/index.md

@@ -42,9 +42,9 @@ Set up your project's merge request settings:
 
 ![project's merge request settings](img/merge_requests_settings.png)
 
-### Service Desk
+### Service Desk **[PREMIUM]**
 
-Enable [Service Desk](https://docs.gitlab.com/ee/user/project/service_desk.html) for your project to offer customer support. Service Desk is available in [GitLab Premium](https://about.gitlab.com/pricing/).
+Enable [Service Desk](https://docs.gitlab.com/ee/user/project/service_desk.html) for your project to offer customer support.
 
 ### Export project
 
@@ -128,3 +128,7 @@ namespace if needed.
 ### Error Tracking
 
 Configure Error Tracking to discover and view [Sentry errors within GitLab](../operations/error_tracking.md).
+
+### Jaeger tracing **[ULTIMATE]**
+
+Add the URL of a Jaeger server to allow your users to [easily access the Jaeger UI from within GitLab](../operations/tracing.md).

doc/user/project/web_ide/index.md

@@ -128,5 +128,123 @@ IDE. An example `package.json` is below.
 }
 ```
 
+## Interactive Web Terminals for the Web IDE **[ULTIMATE ONLY]**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5426) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6.
+
+CAUTION: **Warning:**
+Interactive Web Terminals for the Web IDE is currently in **Beta**.
+
+[Interactive web terminals](../../../ci/interactive_web_terminal/index.md)
+give the user access to a terminal to interact with the Runner directly from
+GitLab, including through the Web IDE.
+
+Only project [**maintainers**](../../permissions.md#project-members-permissions)
+can run Interactive Web Terminals through the Web IDE.
+
+CAUTION: **Warning:**
+GitLab.com [does not support Interactive Web Terminals yet](https://gitlab.com/gitlab-org/gitlab-ce/issues/52611).
+Shared Runners in private instances are not supported either.
+
+### Runner 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/