-
-
Notifications
You must be signed in to change notification settings - Fork 465
/
README.md
171 lines (119 loc) · 5.94 KB
/
README.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
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
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
# PlantUML Server
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://github.com/plantuml/plantuml-server/tags)
[](https://www.plantuml.com/plantuml)
[](https://www.plantuml.com/plantuml)
[](https://www.plantuml.com/plantuml)
[](https://github.com/sponsors/plantuml/)
[](https://hub.docker.com/r/plantuml/plantuml-server)
PlantUML Server is a web application to generate UML diagrams on-the-fly.
[PlantUML is **not** affected by the log4j vulnerability.](https://github.com/plantuml/plantuml/issues/826)
To know more about PlantUML, please visit https://plantuml.com.
## Requirements
- jre/jdk 11 or above
- apache maven 3.0.2 or above
## Recommendations
- Jetty 11 or above
- Tomcat 10 or above
## How to run the server
Just run:
```sh
mvn jetty:run
```
The server is now listening to [http://localhost:8080/plantuml](http://localhost:8080/plantuml).
In this way the server is run on an embedded jetty server.
You can specify the port at which it runs:
```sh
mvn jetty:run -Djetty.http.port=9999
```
## How to run the server with Docker
You can run Plantuml with jetty or tomcat container
```sh
docker run -d -p 8080:8080 plantuml/plantuml-server:jetty
docker run -d -p 8080:8080 plantuml/plantuml-server:tomcat
```
The server is now listening to [http://localhost:8080](http://localhost:8080).
### Read-only container
The jetty container supports read-only files system, you can run the read-only mode with:
```sh
docker run -d -p 8080:8080 --read-only -v /tmp/jetty plantuml/plantuml-server:jetty
```
This makes the container compatible with more restricted environment such as OpenShift, just make sure you mount a volume (can be ephemeral) on `/tmp/jetty`.
### Change base URL
To run plantuml using different base url, change the `docker-compose.yml` file:
```yaml
environment:
- BASE_URL=plantuml
```
And run `docker-compose up`. This will start a modified version of the image using the base url `/plantuml`, e.g. http://localhost:8080/plantuml
## How to set PlantUML options
You can apply some option to your PlantUML server with environment variable.
If you run the directly the jar:
```sh
# NOTE: jetty-runner is deprecated.
# build war file and jetty-runner
mvn package
# start directly
# java $JVM_ARGS -jar jetty-runner.jar $JETTY_ARGS
java -jar target/dependency/jetty-runner.jar --config src/main/config/jetty.xml --port 9999 --path /plantuml target/plantuml.war
# see help for more possible options
java -jar target/dependency/jetty-runner.jar --help
```
Note: `--config src/main/config/jetty.xml` is only necessary if you need support for empty path segments in URLs (e.g. for the old proxy)
Alternatively, start over maven and pass the option with `-D` flag
```sh
mvn jetty:run -D THE_ENV_VARIABLE=THE_ENV_VALUE -Djetty.http.port=9999
```
If you use docker, you can use the `-e` flag:
```sh
docker run -d -p 9999:8080 -e THE_ENV_VARIABLE=THE_ENV_VALUE plantuml/plantuml-server:jetty
```
You can set all the following variables:
* `BASE_URL`
* PlantUML Base URL path
* Default value: `ROOT`
* `PLANTUML_LIMIT_SIZE`
* Limits image width and height
* Default value: `4096`
* `PLANTUML_STATS`
* Set it to `on` to enable [statistics report](https://plantuml.com/statistics-report)
* Default value: `off`
* `HTTP_AUTHORIZATION`
* when calling the `proxy` endpoint, the value of `HTTP_AUTHORIZATION` will be used to set the HTTP Authorization header
* Default value: `null`
* `ALLOW_PLANTUML_INCLUDE`
* Enables `!include` processing which can read files from the server into diagrams. Files are read relative to the current working directory.
* Default value: `false`
## Alternate: How to build your docker image
This method uses maven to run the application. That requires internet connectivity.
So, you can use following command to create a self-contained docker image that will "just-work".
*Note: Generate the WAR (instructions further below) prior to running "docker build"*
```sh
docker image build -f Dockerfile.jetty -t plantuml-server:local .
docker run -d -p 8080:8080 plantuml-server:local
```
The server is now listening to [http://localhost:8080](http://localhost:8080).
You may specify the port in `-p` Docker command line argument.
## How to generate the war
To build the war, just run:
```sh
mvn package
```
at the root directory of the project to produce plantuml.war in the target/ directory.
NOTE: If you want that the generated war includes the `apache-jsp` artifact run:
```sh
mvn package -Dapache-jsp.scope=compile
```
If you want to generate the war with java 8 as target just remove the src/test directory and use `pom.jdk8.xml`.
```sh
rm -rf src/test
mvn package -f pom.jdk8.xml [-Dapache-jsp.scope=compile]
```
## Use with reverse-proxy
It is possible to use PlantUML with a reverse proxy.
You can find this and other examples [here](./examples).