diff options
Diffstat (limited to 'doc/administration/integration')
| -rw-r--r-- | doc/administration/integration/kroki.md | 18 | ||||
| -rw-r--r-- | doc/administration/integration/plantuml.md | 78 | ||||
| -rw-r--r-- | doc/administration/integration/terminal.md | 38 |
3 files changed, 77 insertions, 57 deletions
diff --git a/doc/administration/integration/kroki.md b/doc/administration/integration/kroki.md index dead5640873..5e458399773 100644 --- a/doc/administration/integration/kroki.md +++ b/doc/administration/integration/kroki.md @@ -1,4 +1,10 @@ -# Kroki diagrams **(CORE ONLY)** +--- +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Kroki diagrams **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241744) in GitLab 13.7. @@ -24,6 +30,8 @@ The **Kroki URL** is the hostname of the server running the container. The [`yuzutech/kroki`](https://hub.docker.com/r/yuzutech/kroki) image contains the following diagrams libraries out-of-the-box: +<!-- vale gitlab.Spelling = NO --> + - [Bytefield](https://bytefield-svg.deepsymmetry.org/) - [Ditaa](http://ditaa.sourceforge.net) - [Erd](https://github.com/BurntSushi/erd) @@ -37,6 +45,8 @@ The [`yuzutech/kroki`](https://hub.docker.com/r/yuzutech/kroki) image contains t - [Vega-Lite](https://github.com/vega/vega-lite) - [WaveDrom](https://wavedrom.com/) +<!-- vale gitlab.Spelling = YES --> + If you want to use additional diagram libraries, read the [Kroki installation](https://docs.kroki.io/kroki/setup/install/#_images) to learn how to start Kroki companion containers. @@ -138,8 +148,12 @@ Rel(banking_system, mainframe, "Uses")  +<!-- vale gitlab.Spelling = NO --> + **Nomnoml** +<!-- vale gitlab.Spelling = YES --> + ```plaintext [nomnoml] .... @@ -159,4 +173,4 @@ Rel(banking_system, mainframe, "Uses") .... ``` - + diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md index cd61dc9a2bf..dbbe17cccc8 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.md @@ -5,18 +5,18 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# PlantUML & GitLab +# PlantUML & GitLab **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8537) in GitLab 8.16. When [PlantUML](https://plantuml.com) integration is enabled and configured in -GitLab we are able to create simple diagrams in AsciiDoc and Markdown documents +GitLab you can create diagrams in AsciiDoc and Markdown documents created in snippets, wikis, and repositories. ## PlantUML Server -Before you can enable PlantUML in GitLab; you need to set up your own PlantUML -server that will generate the diagrams. +Before you can enable PlantUML in GitLab; set up your own PlantUML +server to generate the diagrams. ### Docker @@ -26,12 +26,11 @@ With Docker, you can just run a container like this: docker run -d --name plantuml -p 8080:8080 plantuml/plantuml-server:tomcat ``` -The **PlantUML URL** will be the hostname of the server running the container. +The **PlantUML URL** is the hostname of the server running the container. -When running GitLab in Docker, it will need to have access to the PlantUML container. -The easiest way to achieve that is by using [Docker Compose](https://docs.docker.com/compose/). - -A simple `docker-compose.yml` file would be: +When running GitLab in Docker, it must have access to the PlantUML container. +You can achieve that by using [Docker Compose](https://docs.docker.com/compose/). +A basic `docker-compose.yml` file could contain: ```yaml version: "3" @@ -47,13 +46,12 @@ services: container_name: plantuml ``` -In this scenario, PlantUML will be accessible for GitLab at the URL +In this scenario, PlantUML is accessible to GitLab at the URL `http://plantuml:8080/`. ### Debian/Ubuntu -Installing and configuring your -own PlantUML server is easy in Debian/Ubuntu distributions using Tomcat. +You can also install and configure a PlantUML server in Debian/Ubuntu distributions using Tomcat. First you need to create a `plantuml.war` file from the source code: @@ -64,8 +62,7 @@ cd plantuml-server mvn package ``` -The above sequence of commands will generate a WAR file that can be deployed -using Tomcat: +The above sequence of commands generates a `.war` file you can deploy with Tomcat: ```shell sudo apt-get install tomcat8 @@ -74,17 +71,18 @@ sudo chown tomcat8:tomcat8 /var/lib/tomcat8/webapps/plantuml.war sudo service tomcat8 restart ``` -Once the Tomcat service restarts the PlantUML service will be ready and +After the Tomcat service restarts, the PlantUML service is ready and listening for requests on port 8080: ```plaintext http://localhost:8080/plantuml ``` -you can change these defaults by editing the `/etc/tomcat8/server.xml` file. +To change these defaults, edit the `/etc/tomcat8/server.xml` file. -Note that the default URL is different than when using the Docker-based image, -where the service is available at the root of URL with no relative path. Adjust +NOTE: +The default URL is different when using this approach. The Docker-based image +makes the service available at the root URL, with no relative path. Adjust the configuration below accordingly. ### Making local PlantUML accessible using custom GitLab setup @@ -112,7 +110,7 @@ To activate the changes, run the following command: sudo gitlab-ctl reconfigure ``` -Note that the redirection through GitLab **must** be configured +Note that the redirection through GitLab must be configured when running [GitLab with TLS](https://docs.gitlab.com/omnibus/settings/ssl.html) due to PlantUML's use of the insecure HTTP protocol. Newer browsers such as [Google Chrome 86+](https://www.chromestatus.com/feature/4926989725073408) @@ -120,7 +118,7 @@ do not load insecure HTTP resources on a page served over HTTPS. ### Security -PlantUML has features that allows fetching network resources. +PlantUML has features that allow fetching network resources. ```plaintext @startuml @@ -136,18 +134,18 @@ stop; ## GitLab You need to enable PlantUML integration from Settings under Admin Area. To do -that, login with an Admin account and do following: +that, sign in with an Administrator account, and then do following: -- In GitLab, go to **Admin Area > Settings > General**. -- Expand the **PlantUML** section. -- Check **Enable PlantUML** checkbox. -- Set the PlantUML instance as `https://gitlab.example.com/-/plantuml/`. +1. In GitLab, go to **Admin Area > Settings > General**. +1. Expand the **PlantUML** section. +1. Select the **Enable PlantUML** check box. +1. Set the PlantUML instance as `https://gitlab.example.com/-/plantuml/`. NOTE: If you are using a PlantUML server running v1.2020.9 and above (for example, [plantuml.com](https://plantuml.com)), set the `PLANTUML_ENCODING` -environment variable to enable the `deflate` compression. On Omnibus, -this can be done set in `/etc/gitlab.rb`: +environment variable to enable the `deflate` compression. On Omnibus GitLab, +this can be set in `/etc/gitlab.rb`: ```ruby gitlab_rails['env'] = { 'PLANTUML_ENCODING' => 'deflate' } @@ -191,9 +189,11 @@ our AsciiDoc snippets, wikis, and repositories using delimited blocks: Alice -> Bob: hi ``` - You can also use the `uml::` directive for compatibility with [`sphinxcontrib-plantuml`](https://pypi.org/project/sphinxcontrib-plantuml/), but please note that we currently only support the `caption` option. + You can also use the `uml::` directive for compatibility with + [`sphinxcontrib-plantuml`](https://pypi.org/project/sphinxcontrib-plantuml/), + but GitLab only supports the `caption` option. -The above blocks will be converted to an HTML image tag with source pointing to the +The above blocks are converted to an HTML image tag with source pointing to the PlantUML instance. If the PlantUML server is correctly configured, this should render a nice diagram instead of the block: @@ -202,12 +202,18 @@ Bob -> Alice : hello Alice -> Bob : hi ``` -Inside the block you can add any of the supported diagrams by PlantUML such as -[Sequence](https://plantuml.com/sequence-diagram), [Use Case](https://plantuml.com/use-case-diagram), -[Class](https://plantuml.com/class-diagram), [Activity](https://plantuml.com/activity-diagram-legacy), -[Component](https://plantuml.com/component-diagram), [State](https://plantuml.com/state-diagram), -and [Object](https://plantuml.com/object-diagram) diagrams. You do not need to use the PlantUML -diagram delimiters `@startuml`/`@enduml` as these are replaced by the AsciiDoc `plantuml` block. +Inside the block you can add any of the diagrams PlantUML supports, such as: + +- [Sequence](https://plantuml.com/sequence-diagram) +- [Use Case](https://plantuml.com/use-case-diagram) +- [Class](https://plantuml.com/class-diagram) +- [Activity](https://plantuml.com/activity-diagram-legacy) +- [Component](https://plantuml.com/component-diagram) +- [State](https://plantuml.com/state-diagram), +- [Object](https://plantuml.com/object-diagram) + +You do not need to use the PlantUML +diagram delimiters `@startuml`/`@enduml`, as these are replaced by the AsciiDoc `plantuml` block. Some parameters can be added to the AsciiDoc block definition: @@ -217,4 +223,4 @@ Some parameters can be added to the AsciiDoc block definition: - `width`: Width attribute added to the image tag. - `height`: Height attribute added to the image tag. -Markdown does not support any parameters and will always use PNG format. +Markdown does not support any parameters and always uses PNG format. diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md index f4c242b6e72..0f26eb83d17 100644 --- a/doc/administration/integration/terminal.md +++ b/doc/administration/integration/terminal.md @@ -8,14 +8,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7690) in GitLab 8.15. -NOTE: -Only project maintainers and owners can access web terminals. - With the introduction of the [Kubernetes integration](../../user/project/clusters/index.md), -GitLab gained the ability to store and use credentials for a Kubernetes cluster. -One of the things it uses these credentials for is providing access to +GitLab can store and use credentials for a Kubernetes cluster. +GitLab uses these credentials to provide access to [web terminals](../../ci/environments/index.md#web-terminals) for environments. +NOTE: +Only project maintainers and owners can access web terminals. + ## How it works A detailed overview of the architecture of web terminals and how they work @@ -53,15 +53,13 @@ detail below. NOTE: AWS Elastic Load Balancers (ELBs) do not support web sockets. -AWS Application Load Balancers (ALBs) must be used if you want web terminals -to work. See [AWS Elastic Load Balancing Product Comparison](https://aws.amazon.com/elasticloadbalancing/features/#compare) +If you want web terminals to work, use AWS Application Load Balancers (ALBs). +Read [AWS Elastic Load Balancing Product Comparison](https://aws.amazon.com/elasticloadbalancing/features/#compare) for more information. As web terminals use WebSockets, every HTTP/HTTPS reverse proxy in front of -Workhorse needs to be configured to pass the `Connection` and `Upgrade` headers -through to the next one in the chain. If you installed GitLab using Omnibus, or -from source, starting with GitLab 8.15, this should be done by the default -configuration, so there's no need for you to do anything. +Workhorse must be configured to pass the `Connection` and `Upgrade` headers +to the next one in the chain. GitLab is configured by default to do so. However, if you run a [load balancer](../load_balancer.md) in front of GitLab, you may need to make some changes to your configuration. These @@ -73,17 +71,17 @@ guides document the necessary steps for a selection of popular reverse proxies: - [Varnish](https://varnish-cache.org/docs/4.1/users-guide/vcl-example-websockets.html) Workhorse doesn't let WebSocket requests through to non-WebSocket endpoints, so -it's safe to enable support for these headers globally. If you'd rather had a -narrower set of rules, you can restrict it to URLs ending with `/terminal.ws` -(although this may still have a few false positives). +it's safe to enable support for these headers globally. If you prefer a +narrower set of rules, you can restrict it to URLs ending with `/terminal.ws`. +This approach may still result in a few false positives. If you installed from source, or have made any configuration changes to your Omnibus installation before upgrading to 8.15, you may need to make some changes -to your configuration. See the [Upgrading Community Edition and Enterprise -Edition from source](../../update/upgrading_from_source.md#nginx-configuration) -document for more details. +to your configuration. Read +[Upgrading Community Edition and Enterprise Edition from source](../../update/upgrading_from_source.md#nginx-configuration) +for more details. -If you'd like to disable web terminal support in GitLab, just stop passing +To disable web terminal support in GitLab, stop passing the `Connection` and `Upgrade` hop-by-hop headers in the *first* HTTP reverse proxy in the chain. For most users, this is the NGINX server bundled with Omnibus GitLab, in which case, you need to: @@ -104,4 +102,6 @@ they receive a `Connection failed` message. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8413) in GitLab 8.17. Terminal sessions, by default, do not expire. -You can limit terminal session lifetime in your GitLab instance. To do so, navigate to [**Admin Area > Settings > Web terminal**](../../user/admin_area/settings/index.md#general), and set a `max session time`. +You can limit terminal session lifetime in your GitLab instance. To do so, +go to [**Admin Area > Settings > Web terminal**](../../user/admin_area/settings/index.md#general), +and set a `max session time`. |