Skip to content

G
gitlab-ce
Commit 16f640be authored by Amy Qualls's avatar Amy Qualls Committed by Craig Norris
Browse files
Options

Remove the version-specific mentions in page 

We support multiple types of markup. Our docs were overly specific
in a few places.
parent 0987957a
Show whitespace changes
Inline Side-by-side
Showing with 151 additions and 148 deletions
doc/administration/integration/plantuml.md
View file @ 16f640be
......@@ -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**
## PlantUML Server
````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
```
Although you can use the `uml::` directive for compatibility with
[`sphinxcontrib-plantuml`](https://pypi.org/project/sphinxcontrib-plantuml/),
GitLab supports only the `caption` option.
Before you can enable PlantUML in GitLab; set up your own PlantUML
server to generate the diagrams.
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:
```shell
sudo gitlab-ctl reconfigure
```
### Security
### Configure PlantUML security
PlantUML has features that allow fetching network resources.
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.**
## Enable PlantUML integration
## GitLab
After configuring your local PlantUML server, you're ready to enable the 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:
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
----
```
1. Set the PlantUML instance as `https://gitlab.example.com/-/plantuml/`,
and click **Save changes**.
- **reStructuredText**
Depending on your PlantUML and GitLab version numbers, you may also need to take
these steps:
```plaintext
.. plantuml::
:caption: Caption with **bold** and *italic*
- 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:
Bob -> Alice: hello
Alice -> Bob: hi
```ruby
gitlab_rails['env'] = { 'PLANTUML_ENCODING' => 'deflate' }
```
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 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:
```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.
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.
doc/user/admin_area/settings/index.md
View file @ 16f640be
......@@ -35,7 +35,7 @@ Access the default page for admin area settings by navigating to **Admin Area >
| ------ | ----------- |
| [Elasticsearch](../../../integration/elasticsearch.md#enabling-advanced-search) | Elasticsearch integration. Elasticsearch AWS IAM. |
| [Kroki](../../../administration/integration/kroki.md#enable-kroki-in-gitlab) | Allow rendering of diagrams in AsciiDoc and Markdown documents using [kroki.io](https://kroki.io). |
| [PlantUML](../../../administration/integration/plantuml.md#gitlab) | Allow rendering of PlantUML diagrams in AsciiDoc and Markdown documents. |
| [PlantUML](../../../administration/integration/plantuml.md) | Allow rendering of PlantUML diagrams in documents. |
| [Slack application](../../../user/project/integrations/gitlab_slack_application.md#configuration) **(FREE SAAS)** | Slack integration allows you to interact with GitLab via slash commands in a chat window. This option is only available on GitLab.com, though it may be [available for self-managed instances in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/28164). |
| [Third party offers](third_party_offers.md) | Control the display of third party offers. |
| [Snowplow](../../../development/snowplow.md) | Configure the Snowplow integration. |
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7