2017-08-17 22:00:37 +05:30
# PlantUML & GitLab
2019-09-30 21:07:59 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8537) in
> GitLab 8.16.
2017-08-17 22:00:37 +05:30
When [PlantUML ](http://plantuml.com ) integration is enabled and configured in
GitLab we are able to create simple diagrams in AsciiDoc and Markdown documents
created in snippets, wikis, and repos.
## 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:
2019-09-30 21:07:59 +05:30
```sh
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.
### 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:
2019-09-30 21:07:59 +05:30
```sh
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:
2019-09-30 21:07:59 +05:30
```sh
2017-08-17 22:00:37 +05:30
sudo apt-get install tomcat7
sudo cp target/plantuml.war /var/lib/tomcat7/webapps/plantuml.war
sudo chown tomcat7:tomcat7 /var/lib/tomcat7/webapps/plantuml.war
sudo service tomcat7 restart
```
Once the Tomcat service restarts the PlantUML service will be ready and
listening for requests on port 8080:
2019-09-30 21:07:59 +05:30
```text
2017-08-17 22:00:37 +05:30
http://localhost:8080/plantuml
```
you can change these defaults by editing the `/etc/tomcat7/server.xml` file.
## 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.
- Set the PlantUML instance as **PlantUML URL** .
2017-08-17 22:00:37 +05:30
## Creating Diagrams
With PlantUML integration enabled and configured, we can start adding diagrams to
our AsciiDoc snippets, wikis and repos using delimited blocks:
2018-03-17 18:26:18 +05:30
- **Markdown**
2017-08-17 22:00:37 +05:30
2019-09-30 21:07:59 +05:30
````markdown
```plantuml
Bob -> Alice : hello
Alice -> Bob : Go Away
```
````
2018-03-17 18:26:18 +05:30
- **AsciiDoc**
2019-09-30 21:07:59 +05:30
```text
[plantuml, format="png", id="myDiagram", width="200px"]
----
Bob->Alice : hello
Alice -> Bob : Go Away
----
```
2018-03-17 18:26:18 +05:30
- **reStructuredText**
2019-09-30 21:07:59 +05:30
```text
.. 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
Alice -> Bob: Go Away
```
2018-03-17 18:26:18 +05:30
2019-09-30 21:07:59 +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
The above blocks will be converted to an HTML img 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 Integration ](../img/integration/plantuml-example.png )
Inside the block you can add any of the supported diagrams by PlantUML such as
[Sequence ](http://plantuml.com/sequence-diagram ), [Use Case ](http://plantuml.com/use-case-diagram ),
[Class ](http://plantuml.com/class-diagram ), [Activity ](http://plantuml.com/activity-diagram-legacy ),
[Component ](http://plantuml.com/component-diagram ), [State ](http://plantuml.com/state-diagram ),
and [Object ](http://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.
Some parameters can be added to the AsciiDoc block definition:
2019-09-30 21:07:59 +05:30
- *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 img tag.
- *height*: Height attribute added to the img tag.
2017-08-17 22:00:37 +05:30
Markdown does not support any parameters and will always use PNG format.