PlantUML, Docker and NGINX. Your own UML designer.

If you've spent any time in software architecture, you already know the drill: someone asks for “just a quick diagram” and three hours later you're wrestling Visio stencils into submission like you're assembling IKEA furniture with instructions written in Elvish. Sequence diagrams, class diagrams, C4 diagrams, deployment diagrams — pick your poison, they all somehow end up crooked, mislabeled, or one drag-and-drop away from total collapse.

Enter PlantUML — an open-source tool that turns plain text into actual, presentable UML diagrams. No dragging boxes. No arrow-alignment rage-quits. Just text in, diagram out.

I've lost count of how many times I've had to share a diagram mid-meeting and tweak it live while someone squints at their screen going “wait, can you move that arrow.” With PlantUML, that's just... a URL and a text edit. Share the link, get a rendered image back, and whoever's on the other end can edit the syntax too. From here on out, whenever I talk architecture on this blog, I'm including the PlantUML source alongside it — future me will thank present me, and so will you.

But before any of that diagram magic happens, you need somewhere to actually run PlantUML. So this post is the unglamorous prequel: standing up Docker, running the PlantUML server in a container, and putting NGINX in front of it as a reverse proxy. This is where the fun begins... (I know, I know, another Star Wars reference — it's genuinely the site's whole personality at this point). I'm running a Debian-based Linux distro throughout, so adjust your package manager incantations accordingly.

Installing Docker

Crack open a terminal. First, the ceremonial “update everything” step everyone secretly skips and shouldn't:

sudo apt update

Now grab the prerequisite packages Docker needs to function like a civilized container runtime:

sudo apt install apt-transport-https ca-certificates curl gnupg

Install Docker itself:

sudo apt install docker.io

And give it the customary “are you actually alive” check:

sudo systemctl status docker

If that comes back green, congratulations — you now own a whale. 🐳

Installing NGINX

Personal hill I'll die on: the reverse proxy lives directly on the host, not in a container. Call it superstition, call it one too many nested-Docker debugging sessions I never want to repeat.

sudo apt install nginx

If you're exposing this to the actual internet, lock your firewall down to HTTPS only — don't be the reason someone writes a “how I got pwned” blog post about you. For this walkthrough, though, I'm keeping it simple and just opening port 80:

sudo ufw allow 'Nginx HTTP'

Running PlantUML in Docker

Pull the image:

docker pull plantuml/plantuml-server

Spin up the container:

docker run -d -p 8080:8080 plantuml/plantuml-server:jetty

Once that image lands, this line mounts it into a running container. Quick decoder ring for the flags:

• -d — run detached, in the background, like a responsible adult who doesn't tie up their terminal.
• -p — maps host port 8080 to the container's port 8080, PlantUML's default. No surprises here.
• The last bit is just the image name — the thing we actually want to run.

Assuming your firewall isn't standing in the way, point a browser at http://localhost:8080 and the PlantUML designer should greet you like an old friend.

Configuring NGINX as a reverse proxy

Last step: teach NGINX to forward traffic on port 80 (or 443, if you're fancy) to port 8080 where PlantUML is quietly doing its thing, under its own little virtual path.

Open the config:

sudo nano /etc/nginx/nginx.conf

(I use nano. I know vi is more powerful. I also know my own limits and the size of my memory, and this relationship works better when I'm not fighting my editor and my YAML at the same time.)

Find the location / { block and add a new one just above it:

location /plantuml/ {
    proxy_pass http://localhost:8080/;
}

In plain English, this tells NGINX to:

• Set up a virtual path at /plantuml.
• Strip the container's own base path and remap everything underneath /plantuml.
• Proxy all of that traffic straight through to port 8080.

Reload NGINX, and boom — you now own your own personal UML designer, self-hosted, no subscription, no “contact sales” button in sight.

In a future post, I'll actually share some diagram snippets — C4 especially, since apparently I can't stop talking about it. Until next time.