Using PlantUML For Diagrams In A GitLab Wiki

Last Updated on November 25, 2022

If you’ve ever spent any time reading through documentation, you’ll understand the value of a well-placed diagram. It’s a way to cement understanding and explain complex ideas more easily than in text. In this article you’ll learn how to use PlantUML within a GitLab wiki, to provide a collaborative way to create diagrams and keep them up to date.

1. Overview

Unfortunately wiki services often don’t make it easy to create diagrams. This is because wikis are primarily based around editing text-based information.

Often when it comes to creating diagrams, people will use an external service (e.g. LucidChart, PowerPoint) and then upload an image file to the wiki. There are couple of problems with this:

• how can someone edit the diagrams if it needs to be updated?
• even if you were to provide a link or the original file as an attachment, it’s going to be a slow process to edit it
• more often than not, the diagram won’t be updated and will become out of date as the text around it moves on

Fortunately, some clever folks over at PlantUML spotted this problem and have provided a way to render diagrams from text. Below is a simple sequence diagram example:

The fact that PlantUML diagrams are defined using a simple and easy to understand text syntax makes them ideal for wikis. It’s easy to collaborate on the diagrams and keep them bang up-to-date. The above diagrams is represented by code below:

```plantuml
Bob -> Alice : hello
Alice -> Bob : hi
```

You’ll learn about the PlantUML syntax later on.

Although we’ll mainly be looking at sequence diagrams in this article, you can also add class diagrams and state diagrams, among others.

2. Environment setup – a working example

Since I prefer to provide a working example as well as tell you how to implement this, feel free to follow along with the example in this GitHub repository.

We’ll need 2 services to show this working:

1. GitLab – a Git repository manager which also has a wiki feature. The community edition is free and we can use the GitLab Docker image to get up and running quickly.
2. PlantUML – a text based diagram tool. It’s free to use, also with a Docker image available.

How GitLab and PlantUML work together

When a user requests the GitLab wiki page, it returns the diagram’s image URL which points to the PlantUML server, as below:

The image URL itself looks like this:

http://localhost/-/plantuml/png/U9nppCbCJbNGjLDmoa-oKd0iBSb8pIl9J4uioSpFKmXABInDBIxX0iefw0BLE88KOr5LN92VLvpAnUM8QbXUFb1TaK8YTaCXYcrqTI6g4t6fXXeE01dlEfK0

As you can see it is quite long, and in fact contains an encoded string which represents all the information required by PlantUML to render the diagram.

Docker Compose

The easiest way to get an environment up and running is to use Docker Compose. Create a file docker-compose.yml file with the following contents:

version: "3"
services:
  gitlab:
    image: gitlab/gitlab-ce:latest
    ports:
      - 443:443
      - 80:80
      - 22:22
    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:jetty
    ports:
      - 8080:8080

Info: here we’re specifying two Docker containers that should be brought up, for GitLab and PlantUML.

We also specify what ports they should be exposed on.

The NGINX rule you see defined in the environment section of gitlab is a clever way to forward any requests to http://localhost/-/plantuml to the PlantUML Docker container instead.

With this file in place, we can then just run:

docker-compose up -d

If we then run docker ps we can see both containers are now running:

2.1. PlantUML

Navigating to localhost:8080 shows up the PlantUML home page:

This page provides a nice interface for testing out the diagram syntax directly, and seeing what image it renders. We won’t really need to use this page once everything is setup in GitLab.

2.2. GitLab

We now have an instance of GitLab running over at localhost (it may take some time to startup). The first page you’ll be shown asks you to enter a new password. Enter one and hit the blue Change your password button:

You’ll be able to login to GitLab with the default username root and password you just entered. Hit the green Sign in button:

Creating a project

Now choose Create a project:

Enter an amusing value in the Project name field, and click the green Create project button:

Now you have a project, click the Wiki link on the left hand side:

We can now click the green Create your first page button:

Add a title and some content, following the standard GitLab Markdown syntax. See if you can come up with any better jokes than mine. Then click the green Create page button:

Your content will then render beautifully:

Before we can go ahead and start adding PlantUML diagrams though, there’s a configuration option we need to set.

Configuring GitLab

In the top bar click the wrench icon to access the Admin Area:

In the left-hand menu, go to Settings > Integrations:

Click the Expand button to the right of PlantUML. Check the Enable PlantUML checkbox, enter http://localhost/-/plantuml/ in the PlantUML URL field, then click the green Save button:

Info: a request to the http://localhost/-/plantuml URL will be forwarded to PlantUML as per the rule configured earlier in the Docker Compose file.

At this point we now have everything setup to start using PlantUML from within GitLab wikis.

3. Creating some PlantUML diagrams

Go back to the project wiki page we created earlier, and click on the Edit button:

3.1. Basic PlantUML syntax

We can enter PlantUML syntax using the triple backtick ``` Markdown notation.

• ```plantuml starts a diagram definition
• ``` concludes a diagram definition

Enter the following example code somewhere on your page:

```plantuml
Bob -> Alice : hello
Alice -> Bob : hi
```

Click the green Save changes button and you’ll see the diagram render:

Info: a note on syntax. When used within GitLab, we use the Markdown syntax ```plantuml to begin our diagrams and ``` to end them. When used from the PlantUML server directly, we need to use @startuml and @enduml.

3.2. Sequence diagram syntax

Sequence diagrams are a great way to describe the messages between different services. From a developer’s perspective, this could be helpful to describe HTTP requests between different web services, for example.

The basic syntax for a sequence diagram relies on participants (i.e. the services) and messages between them. The participants don’t have to be defined explicitly, but are derived from the message definitions themselves.

Use the arrow -> to define an interaction between two participants. You can add a description of the interaction after the colon :.

Another example

Here’s a slightly more elaborate example:

```plantuml
User -> GitLab : Request wiki page
User <- GitLab : Return PlantUML image URL
User -> PlantUML : Request image
User <- PlantUML
```

Which generates the following diagram:

Two things to note here:

1. You can use -> or <- depending on your preference i.e. User <- PlantUML and PlantUML -> User are the same
2. The message description is optional

Defining participants

You read earlier that participants are derived from the message definitions. That’s true, but they can be defined too which can be useful to:

1. Create a shorthand name for the participant, to refer to in message definitions
2. Define the order that participants appear in diagrams

Say in the diagram above we wanted GitLab to instead say GitLab Community Edition, and for it to appear after PlantUML. We could write the following code, defining a list of participants at the start:

```plantuml
participant User
participant PlantUML
participant "GitLab Community Edition" as GitLab
User -> GitLab : Request wiki page
User <- GitLab : Return PlantUML image URL
User -> PlantUML : Request image
User <- PlantUML
```

Which generates:

Note: we can still refer to GitLab Community Edition as GitLab in all the message definitions.

Advanced level diagrams

There’s no point going over all the syntax, as you can access it yourself from the PlantUML documentation page. For fun though, I’ve included an example of what else you can do with just sequence diagrams alone:

4. Conclusion

You should now be familiar with how to setup GitLab to point to an instance of PlantUML, allowing you to add diagrams to wiki pages. You’ve had an introduction to the syntax for sequence diagrams.

Head on over to the PlantUML web page to find out about all the possibilities you have with this great tool.

5. Resources

GITHUB REPOSITORY
Follow along with this article by checking out the accompanying GitHub repository

PLANTUML
Home page
Sequence diagram docs

GITLAB
Docker Image docs
GitLabMarkdown syntax docs

VIDEO
If you prefer to learn in video format, check out this accompanying video to this post on the Tom Gregory Tech YouTube channel.