Infrastructure-as-Code with PlantUML and Docker

This infrastructure-focused initiative leverages the power of PlantUML, a popular open-source tool for creating diagrams-as-code for infrastructure. With this project, I aim to provide you with a self-contained environment through Docker, including dependencies and tools, such as PlantUML, Nginx, and Java, that allows you to quickly generate diagrams for visualizing your architecture and infrastructure.

While using PlantUML web-based editor in the browser might offer a better user interface, this dockerized project is built around the PlantUML CLI, providing more flexibility, integration possibilities, offline support, version control, and scalability.

You may prefer to create diagrams initially using a web-based editor! No problem. You can then use this project as a template to automate the diagram generation process, incorporate it into build scripts or Continuous Integration/Continuous Deployment (CI/CD) pipelines, and generate diagrams as part of your project documentation.

Table of contents

• Infrastructure-as-Code with PlantUML and Docker
  • Table of contents
  • Features
  • Folder structure overview
  • Prerequisites
  • Get started
    • Option #1: Use VS Code Dev Containers (Recommended)
    • Option #2: Run the Project as a Standalone Container
    • Option #3: Run the Project Locally (Without Docker)
  • Appendix
    • Helpful Docker Commands
  • Roadmap
  • Contributing
  • Acknowledgements

Features

• Diagrams-as-Code: Create and edit diagrams in a code-like format, making it easy for developers to version control and collaborate on visual representations of system architectures, flowcharts, and more.

• Self-Contained Environment: The project uses Docker to set up a development environment, eliminating the need to install PlantUML dependencies manually.

• Automatic Diagram Generation: When working within a VS Code dev containers, diagrams are automatically generated whenever a new .puml diagram is created, edited, or saved in the src/diagrams folder.

• Local Diagram Generation: Run the project outside VS Code dev containers to manually generate diagrams using a simple CLI command.

Folder structure overview

root
├─ .devcontainer             # VS Code dev container configuration
│  └─ devcontainer.json
├─ config                    # Server configuration file
│  └─ nginx-default.conf
├─ libs                      # PlantUML JAR file
│  └─ plantuml-1.2023.10.jar
├─ scripts                   # Helper scripts
│  ├─ entrypoint.sh
│  └─ watch.sh
├─ src                       # Source code and diagrams
│  ├─ build                  # Generated diagrams
│  │  ├─ generated_diagram.svg
│  ├─ diagrams               # Source .puml diagrams
│  │  ├─ source_diagram.puml
│  └─ index.html             # Landing page displaying diagrams
├─ Dockerfile                # Docker image configuration

Prerequisites

• Docker Desktop (recommended for the most straightforward setup). You can install Docker from here.
• VS Code Dev Containers extension (only if you plan to open the project in a dev container).

Get started

There are 3 options you may choose from to get started:

Option #1: Use VS Code Dev Containers (Recommended)

1. Ensure Docker is running on your system.
2. Open the project in VS Code after cloning the repository.
3. If the VS Code Remote - Containers extension is not installed, it will prompt you to install it.
4. Click Reopen in Container when prompted. The dev container will be built automatically.
5. Edit diagrams in the src/diagrams folder. New diagrams will be generated to both the src/build folder and displayed on the web server at the specified port in .devcontainer/devcontainer.json. You can click the link under Ports in VS Code to open the diagrams in your browser.

Option #2: Run the Project as a Standalone Container

1. Ensure Docker is running on your system. Build the Docker image using the following command:

docker build -t <your-image-name> .

2. Run the container with port forwarding and mounting:

docker run -dp 127.0.0.1:8080:8080 -v $(pwd)/src:/workspace/ <your-image-name>:latest

Note: In this command, the src folder is mounted to the /workspace folder in the container. Replace <your-image-name> with a custom name for your Docker image.

3. Access the diagrams in your browser at http://localhost:8080.

Refer to the appendix section below for more helpful Docker commands.

Option #3: Run the Project Locally (Without Docker)

1. Install the PlantUML dependencies manually. For more information, check the official PlantUML website.
2. Generate diagrams using the following command:

java -jar libs/plantuml-1.2023.10.jar -tsvg src/diagrams/source_diagram.puml -o src/build

Appendix

Helpful Docker Commands

The following commands may be helpful during troubleshooting, particularly when running the project as a standalone container (not a VS Code dev container).

Get a list of images:

docker images

Build the Docker image:

docker build -t <your-image-name> .

Start a container with port forwarding and mounting:

docker run -dp 127.0.0.1:8080:8080 -v $(pwd)/src:/workspace/ <your-image-name>:latest

Check container status:

docker ps

View Docker logs:

docker logs <container-id>

Clear image cache to rebuild the image:

docker build --no-cache -t <your-image-name> -f Dockerfile .

Roadmap

• Introduce a new feature to encode diagram text as YAML that can be inserted into diagram entities or elements.

• Implement a script to automatically clean out diagrams from the container's usr/share/nginx/html folder when there is no longer a corresponding source diagram in workspace/diagrams. This ensures that deleted diagrams no longer appear on the landing page, providing a cleaner and more organized visualization experience.

• Automatically load helpful and relevant VS Code extensions in the Dev Container.

  • PlantUML
  • Git
  • vscode-icons

Contributing

I value and appreciate contributions from the community. Whether you want to report a bug, suggest an improvement, or contribute code changes, we welcome your efforts. If you encounter any issues or have questions, please feel free to open an issue. To contribute code changes, fork the repository, create a new branch for your changes, and submit a pull request. Your contributions help make this project better for everyone. I appreciate your support!

Acknowledgements

• PlantUML - A special thanks to PlantUML for providing an excellent tool for creating diagrams as code.