debian-mirror-gitlab/doc/administration/integration/plantuml.md

208 lines
6.5 KiB
Markdown
Raw Normal View History

2017-08-17 22:00:37 +05:30
# PlantUML & GitLab
2020-03-13 15:44:24 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8537) in GitLab 8.16.
2017-08-17 22:00:37 +05:30
2020-04-22 19:07:51 +05:30
When [PlantUML](https://plantuml.com) integration is enabled and configured in
2017-08-17 22:00:37 +05:30
GitLab we are able to create simple diagrams in AsciiDoc and Markdown documents
2020-05-24 23:13:21 +05:30
created in snippets, wikis, and repositories.
2017-08-17 22:00:37 +05:30
## PlantUML Server
Before you can enable PlantUML in GitLab; you need to set up your own PlantUML
2018-03-27 19:54:05 +05:30
server that will generate the diagrams.
### Docker
With Docker, you can just run a container like this:
2020-03-13 15:44:24 +05:30
```shell
2019-09-30 21:07:59 +05:30
docker run -d --name plantuml -p 8080:8080 plantuml/plantuml-server:tomcat
```
2018-03-27 19:54:05 +05:30
The **PlantUML URL** will be the hostname of the server running the container.
2019-12-21 20:55:43 +05:30
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:
```yaml
version: "3"
services:
gitlab:
image: 'gitlab/gitlab-ce:12.2.5-ce.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
```
In this scenario, PlantUML will be accessible for GitLab at the URL
`http://plantuml:8080/`.
2018-03-27 19:54:05 +05:30
### Debian/Ubuntu
Installing and configuring your
2017-08-17 22:00:37 +05:30
own PlantUML server is easy in Debian/Ubuntu distributions using Tomcat.
First you need to create a `plantuml.war` file from the source code:
2020-03-13 15:44:24 +05:30
```shell
2019-09-04 21:01:54 +05:30
sudo apt-get install graphviz openjdk-8-jdk git-core maven
2017-08-17 22:00:37 +05:30
git clone https://github.com/plantuml/plantuml-server.git
cd plantuml-server
mvn package
```
The above sequence of commands will generate a WAR file that can be deployed
using Tomcat:
2020-01-01 13:55:28 +05:30
```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
2017-08-17 22:00:37 +05:30
```
Once the Tomcat service restarts the PlantUML service will be ready and
listening for requests on port 8080:
2020-05-24 23:13:21 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
http://localhost:8080/plantuml
```
2020-01-01 13:55:28 +05:30
you can change these defaults by editing the `/etc/tomcat8/server.xml` file.
2017-08-17 22:00:37 +05:30
2019-12-21 20:55:43 +05:30
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
the configuration below accordingly.
2019-12-04 20:38:33 +05:30
### Making local PlantUML accessible using custom GitLab setup
The PlantUML server runs locally on your server, so it is not accessible
externally. As such, it is necessary to catch external PlantUML calls and
redirect them to the local server.
The idea is to redirect each call to `https://gitlab.example.com/-/plantuml/`
2019-12-21 20:55:43 +05:30
to the local PlantUML server `http://plantuml:8080/` or `http://localhost:8080/plantuml/`, depending on your setup.
2019-12-04 20:38:33 +05:30
To enable the redirection, add the following line in `/etc/gitlab/gitlab.rb`:
```ruby
2019-12-21 20:55:43 +05:30
# Docker deployment
nginx['custom_gitlab_server_config'] = "location /-/plantuml/ { \n proxy_cache off; \n proxy_pass http://plantuml:8080/; \n}\n"
# Built from source
2019-12-26 22:10:19 +05:30
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"
2019-12-21 20:55:43 +05:30
```
To activate the changes, run the following command:
2020-03-13 15:44:24 +05:30
```shell
2019-12-21 20:55:43 +05:30
sudo gitlab-ctl reconfigure
2019-12-04 20:38:33 +05:30
```
2020-06-23 00:09:42 +05:30
### Security
PlantUML has features that allows fetching network resources.
```plaintext
@startuml
start
' ...
!include http://localhost/
stop;
@enduml
```
**If you self-host the PlantUML server, network controls should be put in place to isolate it.**
2017-08-17 22:00:37 +05:30
## GitLab
You need to enable PlantUML integration from Settings under Admin Area. To do
that, login with an Admin account and do following:
2019-09-30 21:07:59 +05:30
- In GitLab, go to **Admin Area > Settings > Integrations**.
- Expand the **PlantUML** section.
- Check **Enable PlantUML** checkbox.
2019-12-04 20:38:33 +05:30
- Set the PlantUML instance as `https://gitlab.example.com/-/plantuml/`.
2017-08-17 22:00:37 +05:30
2020-07-28 23:09:34 +05:30
NOTE: **Note:**
If you are using a PlantUML server running v1.2020.9 and
2020-05-24 23:13:21 +05:30
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`:
```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.
2017-08-17 22:00:37 +05:30
## Creating Diagrams
With PlantUML integration enabled and configured, we can start adding diagrams to
2020-05-24 23:13:21 +05:30
our AsciiDoc snippets, wikis, and repositories using delimited blocks:
2017-08-17 22:00:37 +05:30
2018-03-17 18:26:18 +05:30
- **Markdown**
2017-08-17 22:00:37 +05:30
2020-04-08 14:13:33 +05:30
````markdown
2019-09-30 21:07:59 +05:30
```plantuml
Bob -> Alice : hello
2019-12-21 20:55:43 +05:30
Alice -> Bob : hi
2019-09-30 21:07:59 +05:30
```
2020-04-08 14:13:33 +05:30
````
2018-03-17 18:26:18 +05:30
- **AsciiDoc**
2020-05-24 23:13:21 +05:30
```plaintext
2019-09-30 21:07:59 +05:30
[plantuml, format="png", id="myDiagram", width="200px"]
----
Bob->Alice : hello
2019-12-21 20:55:43 +05:30
Alice -> Bob : hi
2019-09-30 21:07:59 +05:30
----
```
2018-03-17 18:26:18 +05:30
- **reStructuredText**
2020-05-24 23:13:21 +05:30
```plaintext
2019-09-30 21:07:59 +05:30
.. plantuml::
:caption: Caption with **bold** and *italic*
2018-03-17 18:26:18 +05:30
2019-09-30 21:07:59 +05:30
Bob -> Alice: hello
2019-12-21 20:55:43 +05:30
Alice -> Bob: hi
2019-09-30 21:07:59 +05:30
```
2018-03-17 18:26:18 +05:30
2020-04-08 14:13:33 +05:30
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.
2017-08-17 22:00:37 +05:30
2020-04-08 14:13:33 +05:30
The above blocks will be converted to an HTML image tag with source pointing to the
2017-08-17 22:00:37 +05:30
PlantUML instance. If the PlantUML server is correctly configured, this should
render a nice diagram instead of the block:
2019-12-21 20:55:43 +05:30
```plantuml
Bob -> Alice : hello
Alice -> Bob : hi
```
2017-08-17 22:00:37 +05:30
Inside the block you can add any of the supported diagrams by PlantUML such as
2020-04-22 19:07:51 +05:30
[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
2017-08-17 22:00:37 +05:30
diagram delimiters `@startuml`/`@enduml` as these are replaced by the AsciiDoc `plantuml` block.
Some parameters can be added to the AsciiDoc block definition:
2020-05-24 23:13:21 +05:30
- `format`: Can be either `png` or `svg`. Note that `svg` is not supported by
2019-09-30 21:07:59 +05:30
all browsers so use with care. The default is `png`.
2020-05-24 23:13:21 +05:30
- `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.
2017-08-17 22:00:37 +05:30
Markdown does not support any parameters and will always use PNG format.