1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
|
---
stage: Create
group: Source Code
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"
type: reference, howto
---
# PlantUML and GitLab **(FREE)**
When the [PlantUML](https://plantuml.com) integration is enabled and configured in
GitLab, you can create diagrams in snippets, wikis, and repositories. This integration
is enabled on GitLab.com for all SaaS users and does not require any additional configuration.
To set up the integration on a self-managed instance, 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** files with the extension `.md`:
````markdown
```plantuml
Bob -> Alice : hello
Alice -> Bob : hi
```
````
For additional acceptable extensions, review the
[`languages.yaml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/vendor/languages.yml#L3174) file.
- **AsciiDoc** files with the extension `.asciidoc`, `.adoc`, or `.asc`:
```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.
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
To run a PlantUML container in Docker, run this command:
```shell
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.
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"
services:
gitlab:
image: 'gitlab/gitlab-ee:12.2.5-ee.0'
environment:
GITLAB_OMNIBUS_CONFIG: |
nginx['custom_gitlab_server_config'] = "location /-/plantuml/ { \n proxy_cache off; \n proxy_pass http://plantuml:8080/; \n}\n"
plantuml:
image: 'plantuml/plantuml-server:tomcat'
container_name: plantuml
```
### Debian/Ubuntu
You can install and configure a PlantUML server in Debian/Ubuntu distributions
using Tomcat:
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
```
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
```
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.
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.
## Configure local PlantUML access
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:
- `http://plantuml:8080/`
- `http://localhost:8080/plantuml/`
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.
To enable this redirection:
1. Add the following line in `/etc/gitlab/gitlab.rb`, depending on your setup method:
```ruby
# Docker deployment
nginx['custom_gitlab_server_config'] = "location /-/plantuml/ { \n proxy_cache off; \n proxy_pass http://plantuml:8080/; \n}\n"
# 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. To activate the changes, run the following command:
```shell
sudo gitlab-ctl reconfigure
```
### 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
start
' ...
!include http://localhost/
stop;
@enduml
```
## Enable PlantUML integration
After configuring your local PlantUML server, you're ready to enable the PlantUML integration:
1. Sign in to GitLab as an [Administrator](../../user/permissions.md) user.
1. On the top bar, select **Main menu > Admin**.
1. On the left sidebar, go to **Settings > General** and expand the **PlantUML** section.
1. Select the **Enable PlantUML** checkbox.
1. Set the PlantUML instance as `https://gitlab.example.com/-/plantuml/`,
and select **Save changes**.
Depending on your PlantUML and GitLab version numbers, you may also need to take
these steps:
- 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:
```ruby
gitlab_rails['env'] = { 'PLANTUML_ENCODING' => 'deflate' }
```
In GitLab Helm chart, you can set it by adding a variable to the
[global.extraEnv](https://gitlab.com/gitlab-org/charts/gitlab/blob/master/doc/charts/globals.md#extraenv)
section, like this:
```yaml
global:
extraEnv:
PLANTUML_ENCODING: deflate
```
- 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.
|
