plantuml.md 3.9 KB
Newer Older
1 2
# PlantUML & GitLab

3
> [Introduced][ce-8537] in GitLab 8.16.
4 5

When [PlantUML](http://plantuml.com) integration is enabled and configured in
6 7
GitLab we are able to create simple diagrams in AsciiDoc and Markdown documents
created in snippets, wikis, and repos.
8 9 10 11

## PlantUML Server

Before you can enable PlantUML in GitLab; you need to set up your own PlantUML
12 13 14 15 16 17 18 19 20 21 22 23 24
server that will generate the diagrams.

### Docker

With Docker, you can just run a container like this:

`docker run -d --name plantuml -p 8080:8080 plantuml/plantuml-server:tomcat`

The **PlantUML URL** will be the hostname of the server running the container.

### Debian/Ubuntu

Installing and configuring your
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42
own PlantUML server is easy in Debian/Ubuntu distributions using Tomcat.

First you need to create a `plantuml.war` file from the source code:

```
sudo apt-get install graphviz openjdk-7-jdk git-core maven
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:

```
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
43
sudo service tomcat7 restart
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
```

Once the Tomcat service restarts the PlantUML service will be ready and
listening for requests on port 8080:

```
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:

 - in GitLab go to **Admin Area** and then **Settings**
 - scroll to bottom of the page until PlantUML section
 - check **Enable PlantUML** checkbox
 - set the PlantUML instance as **PlantUML URL**

## Creating Diagrams

With PlantUML integration enabled and configured, we can start adding diagrams to
69
our AsciiDoc snippets, wikis and repos using delimited blocks:
70

71 72
- **Markdown**

73 74 75 76
    <pre>
    ```plantuml
    Bob -> Alice : hello
    Alice -> Bob : Go Away
77
    ```</pre>
78

79
- **AsciiDoc**
80

81
    ```
82
    [plantuml, format="png", id="myDiagram", width="200px"]
83
    ----
84
    Bob->Alice : hello
85
    Alice -> Bob : Go Away
86
    ----
87
    ```
88

89
- **reStructuredText**
90

91
    ```
92 93
    .. plantuml::
       :caption: Caption with **bold** and *italic*
94

95 96
       Bob -> Alice: hello
       Alice -> Bob: Go Away
97
    ```
98 99

    You can also use the `uml::` directive for compatibility with [sphinxcontrib-plantuml](https://pypi.python.org/pypi/sphinxcontrib-plantuml), but please note that we currently only support the `caption` option.
100

101
The above blocks will be converted to an HTML img tag with source pointing to the
102 103 104 105 106 107 108 109 110 111 112 113
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.

114
Some parameters can be added to the AsciiDoc block definition:
115 116 117 118 119 120 121

 - *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.

122
Markdown does not support any parameters and will always use PNG format.
123

124
[ce-8537]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8537