diff options
Diffstat (limited to 'doc/administration/integration')
-rw-r--r-- | doc/administration/integration/kroki.md | 2 | ||||
-rw-r--r-- | doc/administration/integration/plantuml.md | 297 | ||||
-rw-r--r-- | doc/administration/integration/terminal.md | 2 |
3 files changed, 152 insertions, 149 deletions
diff --git a/doc/administration/integration/kroki.md b/doc/administration/integration/kroki.md index 5e458399773..9e9ea62c44e 100644 --- a/doc/administration/integration/kroki.md +++ b/doc/administration/integration/kroki.md @@ -56,7 +56,7 @@ You need to enable Kroki integration from Settings under Admin Area. To do that, log in with an administrator account and follow these steps: 1. Select the Admin Area (**{admin}**) icon. -1. Navigate to **Settings > General**. +1. Go to **Settings > General**. 1. Expand the **Kroki** section. 1. Select **Enable Kroki** checkbox. 1. Enter the **Kroki URL**. diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md index dbbe17cccc8..834f4047fdd 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.md @@ -5,22 +5,94 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# PlantUML & GitLab **(FREE)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8537) in GitLab 8.16. +# PlantUML and GitLab **(FREE)** When [PlantUML](https://plantuml.com) integration is enabled and configured in -GitLab you can create diagrams in AsciiDoc and Markdown documents -created in snippets, wikis, and repositories. +GitLab, you can create diagrams in snippets, wikis, and repositories. To set up +the integration, you must: + +1. [Configure your PlantUML server](#configure-your-plantuml-server). +1. [Configure local PlantUML access](#configure-local-plantuml-access). +1. [Configure PlantUML security](#configure-plantuml-security). +1. [Enable the integration](#enable-plantuml-integration). + +After completing the integration, PlantUML converts `plantuml` +blocks to an HTML image tag, with the source pointing to the PlantUML instance. The PlantUML +diagram delimiters `@startuml`/`@enduml` aren't required, as these are replaced +by the `plantuml` block: + +- **Markdown** + + ````markdown + ```plantuml + Bob -> Alice : hello + Alice -> Bob : hi + ``` + ```` + +- **AsciiDoc** + + ```plaintext + [plantuml, format="png", id="myDiagram", width="200px"] + ---- + Bob->Alice : hello + Alice -> Bob : hi + ---- + ``` + +- **reStructuredText** -## PlantUML Server + ```plaintext + .. plantuml:: + :caption: Caption with **bold** and *italic* + + Bob -> Alice: hello + Alice -> Bob: hi + ``` -Before you can enable PlantUML in GitLab; set up your own PlantUML -server to generate the diagrams. + Although you can use the `uml::` directive for compatibility with + [`sphinxcontrib-plantuml`](https://pypi.org/project/sphinxcontrib-plantuml/), + GitLab supports only the `caption` option. + +If the PlantUML server is correctly configured, these examples should render a +diagram instead of the code block: + +```plantuml +Bob -> Alice : hello +Alice -> Bob : hi +``` + +Inside the block you can add any of the diagrams PlantUML supports, such as: + +- [Activity](https://plantuml.com/activity-diagram-legacy) +- [Class](https://plantuml.com/class-diagram) +- [Component](https://plantuml.com/component-diagram) +- [Object](https://plantuml.com/object-diagram) +- [Sequence](https://plantuml.com/sequence-diagram) +- [State](https://plantuml.com/state-diagram) +- [Use Case](https://plantuml.com/use-case-diagram) + +You can add parameters to block definitions: + +- `format`: Can be either `png` (default) or `svg`. Use `svg` with care, as it's + not supported by all browsers, and isn't supported by Markdown. +- `id`: A CSS ID added to the diagram HTML tag. +- `width`: Width attribute added to the image tag. +- `height`: Height attribute added to the image tag. + +Markdown does not support any parameters, and always uses PNG format. + +## Configure your PlantUML server + +Before you can enable PlantUML in GitLab, set up your own PlantUML +server to generate the diagrams: + +- [In Docker](#docker). +- [In Debian/Ubuntu](#debianubuntu). ### Docker -With Docker, you can just run a container like this: +To run a PlantUML container in Docker, run this command: ```shell docker run -d --name plantuml -p 8080:8080 plantuml/plantuml-server:tomcat @@ -29,8 +101,9 @@ docker run -d --name plantuml -p 8080:8080 plantuml/plantuml-server:tomcat The **PlantUML URL** is the hostname of the server running the container. 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: +To achieve that, use [Docker Compose](https://docs.docker.com/compose/). +In this basic `docker-compose.yml` file, PlantUML is accessible to GitLab at the URL +`http://plantuml:8080/`: ```yaml version: "3" @@ -46,37 +119,32 @@ services: container_name: plantuml ``` -In this scenario, PlantUML is accessible to GitLab at the URL -`http://plantuml:8080/`. - ### Debian/Ubuntu -You can also install and configure a PlantUML server in Debian/Ubuntu distributions using Tomcat. +You can 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: +1. Run these commands to create a `plantuml.war` file from the source code: -```shell -sudo apt-get install graphviz openjdk-8-jdk git-core maven -git clone https://github.com/plantuml/plantuml-server.git -cd plantuml-server -mvn package -``` + ```shell + sudo apt-get install graphviz openjdk-8-jdk git-core maven + git clone https://github.com/plantuml/plantuml-server.git + cd plantuml-server + mvn package + ``` -The above sequence of commands generates a `.war` file you can deploy with Tomcat: +1. Deploy the `.war` file from the previous step with these commands: -```shell -sudo apt-get install tomcat8 -sudo cp target/plantuml.war /var/lib/tomcat8/webapps/plantuml.war -sudo chown tomcat8:tomcat8 /var/lib/tomcat8/webapps/plantuml.war -sudo service tomcat8 restart -``` + ```shell + sudo apt-get install tomcat8 + sudo cp target/plantuml.war /var/lib/tomcat8/webapps/plantuml.war + sudo chown tomcat8:tomcat8 /var/lib/tomcat8/webapps/plantuml.war + sudo service tomcat8 restart + ``` -After the Tomcat service restarts, the PlantUML service is ready and -listening for requests on port 8080: - -```plaintext -http://localhost:8080/plantuml -``` +The Tomcat service should restart. After the restart is complete, the +PlantUML service is ready and listening for requests on port 8080: +`http://localhost:8080/plantuml` To change these defaults, edit the `/etc/tomcat8/server.xml` file. @@ -85,40 +153,44 @@ 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 +## Configure local PlantUML access -The PlantUML server runs locally on your server, so it is not accessible -externally by default. As such, it is necessary to catch external PlantUML -calls and redirect them to the local server. +The PlantUML server runs locally on your server, so it can't be accessed +externally by default. Your server must catch external PlantUML +calls to `https://gitlab.example.com/-/plantuml/` and redirect them to the +local PlantUML server. Depending on your setup, the URL is either of the +following: -The idea is to redirect each call to `https://gitlab.example.com/-/plantuml/` -to the local PlantUML server `http://plantuml:8080/` or `http://localhost:8080/plantuml/`, depending on your setup. +- `http://plantuml:8080/` +- `http://localhost:8080/plantuml/` -To enable the redirection, add the following line in `/etc/gitlab/gitlab.rb`: +If you're running [GitLab with TLS](https://docs.gitlab.com/omnibus/settings/ssl.html) +you must configure this redirection, because PlantUML uses the insecure HTTP protocol. +Newer browsers such as [Google Chrome 86+](https://www.chromestatus.com/feature/4926989725073408) +don't load insecure HTTP resources on pages served over HTTPS. -```ruby -# Docker deployment -nginx['custom_gitlab_server_config'] = "location /-/plantuml/ { \n proxy_cache off; \n proxy_pass http://plantuml:8080/; \n}\n" +To enable this redirection: -# Built from source -nginx['custom_gitlab_server_config'] = "location /-/plantuml { \n rewrite ^/-/(plantuml.*) /$1 break;\n proxy_cache off; \n proxy_pass http://localhost:8080/plantuml; \n}\n" -``` +1. Add the following line in `/etc/gitlab/gitlab.rb`, depending on your setup method: -To activate the changes, run the following command: + ```ruby + # Docker deployment + nginx['custom_gitlab_server_config'] = "location /-/plantuml/ { \n proxy_cache off; \n proxy_pass http://plantuml:8080/; \n}\n" -```shell -sudo gitlab-ctl reconfigure -``` + # Built from source + nginx['custom_gitlab_server_config'] = "location /-/plantuml { \n rewrite ^/-/(plantuml.*) /$1 break;\n proxy_cache off; \n proxy_pass http://localhost:8080/plantuml; \n}\n" + ``` -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) -do not load insecure HTTP resources on a page served over HTTPS. +1. To activate the changes, run the following command: -### Security + ```shell + sudo gitlab-ctl reconfigure + ``` -PlantUML has features that allow fetching network resources. +### Configure PlantUML security + +PlantUML has features that allow fetching network resources. If you self-host the +PlantUML server, put network controls in place to isolate it. ```plaintext @startuml @@ -129,98 +201,29 @@ stop; @enduml ``` -**If you self-host the PlantUML server, network controls should be put in place to isolate it.** - -## GitLab +## Enable PlantUML integration -You need to enable PlantUML integration from Settings under Admin Area. To do -that, sign in with an Administrator account, and then do following: +After configuring your local PlantUML server, you're ready to enable the PlantUML integration: -1. In GitLab, go to **Admin Area > Settings > General**. -1. Expand the **PlantUML** section. +1. Sign in to GitLab as an [Administrator](../../user/permissions.md) user. +1. In the top menu, click **{admin}** **Admin Area**. +1. In the left sidebar, go to **Settings > General** and 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 GitLab, -this can be set in `/etc/gitlab.rb`: - -```ruby -gitlab_rails['env'] = { 'PLANTUML_ENCODING' => 'deflate' } -``` - -From GitLab 13.1 and later, PlantUML integration now -[requires a header prefix in the URL](https://github.com/plantuml/plantuml/issues/117#issuecomment-6235450160) -to distinguish different encoding types. - -## Creating Diagrams - -With PlantUML integration enabled and configured, we can start adding diagrams to -our AsciiDoc snippets, wikis, and repositories using delimited blocks: - -- **Markdown** - - ````markdown - ```plantuml - Bob -> Alice : hello - Alice -> Bob : hi - ``` - ```` - -- **AsciiDoc** - - ```plaintext - [plantuml, format="png", id="myDiagram", width="200px"] - ---- - Bob->Alice : hello - Alice -> Bob : hi - ---- - ``` - -- **reStructuredText** - - ```plaintext - .. plantuml:: - :caption: Caption with **bold** and *italic* - - Bob -> Alice: hello - Alice -> Bob: hi - ``` +1. Set the PlantUML instance as `https://gitlab.example.com/-/plantuml/`, + and click **Save changes**. - 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. +Depending on your PlantUML and GitLab version numbers, you may also need to take +these steps: -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: +- For PlantUML servers running v1.2020.9 and above, such as [plantuml.com](https://plantuml.com), + you must set the `PLANTUML_ENCODING` environment variable to enable the `deflate` + compression. In Omnibus GitLab, you can set this value in `/etc/gitlab.rb` with + this command: -```plantuml -Bob -> Alice : hello -Alice -> Bob : hi -``` - -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: - -- `format`: Can be either `png` or `svg`. Note that `svg` is not supported by - all browsers so use with care. The default is `png`. -- `id`: A CSS ID added to the diagram HTML tag. -- `width`: Width attribute added to the image tag. -- `height`: Height attribute added to the image tag. + ```ruby + gitlab_rails['env'] = { 'PLANTUML_ENCODING' => 'deflate' } + ``` -Markdown does not support any parameters and always uses PNG format. +- For GitLab versions 13.1 and later, PlantUML integration now + [requires a header prefix in the URL](https://github.com/plantuml/plantuml/issues/117#issuecomment-6235450160) + to distinguish different encoding types. diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md index 0f26eb83d17..644e2d905ae 100644 --- a/doc/administration/integration/terminal.md +++ b/doc/administration/integration/terminal.md @@ -4,7 +4,7 @@ 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 --- -# Web terminals +# Web terminals **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7690) in GitLab 8.15. |