diff --git a/README.md b/README.md index d7c03b0..256f240 100644 --- a/README.md +++ b/README.md @@ -167,17 +167,4 @@ mvn package -f pom.jdk8.xml [-Dapache-jsp.scope=compile] It is possible to use PlantUML with a reverse proxy. -Here is an example of setting for nginx reverse proxy. - -``` -# PlantUML -location /plantuml/ { - include /etc/nginx/proxy.conf; - - proxy_set_header HOST $host/plantuml; - proxy_set_header X-Forwarded-Host $host/plantuml; - proxy_set_header X-Forwarded-Proto $scheme; - - proxy_pass http://plantuml-server:8080/; -} -``` +You can find this and other examples [here](./examples). diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..d75ad03 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,4 @@ +# Examples + +- [Nginx simple reverse proxy example](./nginx-simple) +- [Nginx reverse proxy example with defined location directive (different context path)](./nginx-contextpath) diff --git a/examples/nginx-contextpath/README.md b/examples/nginx-contextpath/README.md new file mode 100644 index 0000000..2a9b279 --- /dev/null +++ b/examples/nginx-contextpath/README.md @@ -0,0 +1,104 @@ +# Nginx reverse proxy example with defined location directive + +In this example, the reverse proxy is defined only under the `/plantuml` context path. +All other context paths (locations) are not affected and are freely available. +This allows the server to be used for more than "just" PlantUML. + +References: +- [Nginx documentation](https://nginx.org/en/docs/) +- [Nginx beginner's guide](https://nginx.org/en/docs/beginners_guide.html) + + +## Quick start + +Be sure to have [`docker-compose.yml`](./docker-compose.yml) and [`nginx.conf`](./nginx.conf) inside your current working directory. + +```bash +# start nginx and plantuml server +docker-compose up -d + +# stop nginx and plantuml server +docker-compose down +``` + +Check with `docker ps` if both container are up and running: + +``` +$ docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +217e753a0dcf plantuml/plantuml-server:jetty "/entrypoint.sh" 4 seconds ago Up 3 seconds 8080/tcp plantuml-server +9b1290c100f5 nginx:alpine "/docker-entrypoint.…" 4 seconds ago Up 3 seconds 0.0.0.0:80->80/tcp, :::80->80/tcp nginx +``` + +Open [http://localhost/plantuml](http://localhost/plantuml) inside your browser. +YEAH! You are now using PlantUML behind a simple Nginx reverse proxy. + + +## Nginx configuration + +```nginx +... + +# PlantUML +location /plantuml/ { + proxy_set_header HOST $host; + proxy_set_header X-Forwarded-Host $host; + proxy_set_header X-Forwarded-Proto $scheme; + + proxy_pass http://plantuml-server:8080/plantuml/; +} + +... +``` + +- `location /plantuml/` to reverse only the context path `/plantuml` +- `proxy_set_header HOST $host` and `proxy_set_header X-Forwarded-Host $host` to replaces local plantuml server ip with FQDN +- `proxy_set_header X-Forwarded-Proto $scheme` to use reverse proxy protocol schema instead of communication schema between reverse proxy and plantuml server +- `proxy_pass http://plantuml-server:8080/plantuml/` to set reverse proxy path to plantuml server. + Use the docker container name `plantuml-server` instead of ip addresses. + Also, use the same context path (`BASE_URL`) as PlantUML, which is configurable as an environment variable in the docker-compose file. + + +## Nginx and PlantUML server + +```yaml +version: "3" + +services: + plantuml-server: + image: plantuml/plantuml-server:jetty + container_name: plantuml-server + environment: + - TZ="Europe/Berlin" + - BASE_URL="plantuml" + + nginx: + image: nginx:alpine + container_name: nginx + ports: + - "80:80" + environment: + - TZ="Europe/Berlin" + volumes: + - ./nginx.conf:/etc/nginx/nginx.conf:ro +``` + +- Set `container_name` to use them instead of e.g. ip addresses +- Set the environment `TZ` the ensure the same timezone. + For example to server timezone (`cat /etc/timezone`)? +- plantuml-server + * plantuml-server already exposes port `8080` to it's own local network (but not outside). + Since plantuml-server and nginx are sharing a network, nginx can reach plantuml-server without further settings. + * Set the environment `BASE_URL` to the preferred context path +- nginx + * open/link port `80` to the outside + * `./nginx.conf:/etc/nginx/nginx.conf:ro` to use your own Nginx configuration (readonly) + + +## Useful commands + +```bash +# see whats going on inside your docker containers +docker logs --tail 50 --follow --timestamps nginx +docker logs --tail 50 --follow --timestamps plantuml-server +``` diff --git a/examples/nginx-contextpath/docker-compose.yml b/examples/nginx-contextpath/docker-compose.yml new file mode 100644 index 0000000..ea72d0c --- /dev/null +++ b/examples/nginx-contextpath/docker-compose.yml @@ -0,0 +1,19 @@ +version: "3" + +services: + plantuml-server: + image: plantuml/plantuml-server:jetty + container_name: plantuml-server + environment: + - TZ="Europe/Berlin" + - BASE_URL="plantuml" + + nginx: + image: nginx:alpine + container_name: nginx + ports: + - "80:80" + environment: + - TZ="Europe/Berlin" + volumes: + - ./nginx.conf:/etc/nginx/nginx.conf:ro diff --git a/examples/nginx-contextpath/nginx.conf b/examples/nginx-contextpath/nginx.conf new file mode 100644 index 0000000..e5f2852 --- /dev/null +++ b/examples/nginx-contextpath/nginx.conf @@ -0,0 +1,48 @@ +user nginx; +worker_processes auto; + +error_log /var/log/nginx/error.log notice; +pid /var/run/nginx.pid; + +include /etc/nginx/modules-enabled/*.conf; + +events { + worker_connections 1024; +} + +http { + + server { + listen 80; + server_name localhost; + + # PlantUML + location /plantuml/ { + proxy_set_header HOST $host; + proxy_set_header X-Forwarded-Host $host; + proxy_set_header X-Forwarded-Proto $scheme; + + proxy_pass http://plantuml-server:8080/plantuml/; + } + } + + client_max_body_size 0; + + include /etc/nginx/mime.types; + default_type application/octet-stream; + + log_format main '$remote_addr - $remote_user [$time_local] "$request" ' + '$status $body_bytes_sent "$http_referer" ' + '"$http_user_agent" "$http_x_forwarded_for"'; + + access_log /var/log/nginx/access.log main; + + sendfile on; + #tcp_nopush on; + + keepalive_timeout 65; + + #gzip on; + + include /etc/nginx/conf.d/*.conf; +} diff --git a/examples/nginx-simple/README.md b/examples/nginx-simple/README.md new file mode 100644 index 0000000..5957a09 --- /dev/null +++ b/examples/nginx-simple/README.md @@ -0,0 +1,97 @@ +# Nginx simple reverse proxy example + +References: +- [Nginx documentation](https://nginx.org/en/docs/) +- [Nginx beginner's guide](https://nginx.org/en/docs/beginners_guide.html) + + +## Quick start + +Be sure to have [`docker-compose.yml`](./docker-compose.yml) and [`nginx.conf`](./nginx.conf) inside your current working directory. + +```bash +# start nginx and plantuml server +docker-compose up -d + +# stop nginx and plantuml server +docker-compose down +``` + +Check with `docker ps` if both container are up and running: + +``` +$ docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +217e753a0dcf plantuml/plantuml-server:jetty "/entrypoint.sh" 4 seconds ago Up 3 seconds 8080/tcp plantuml-server +9b1290c100f5 nginx:alpine "/docker-entrypoint.…" 4 seconds ago Up 3 seconds 0.0.0.0:80->80/tcp, :::80->80/tcp nginx +``` + +Open [http://localhost](http://localhost) inside your browser. +YEAH! You are now using PlantUML behind a simple Nginx reverse proxy. + + +## Nginx configuration + +```nginx +... + +# PlantUML +location / { + proxy_set_header HOST $host; + proxy_set_header X-Forwarded-Host $host; + proxy_set_header X-Forwarded-Proto $scheme; + + proxy_pass http://plantuml-server:8080/; +} + +... +``` + +- `location /` to reverse complete server +- `proxy_set_header HOST $host` and `proxy_set_header X-Forwarded-Host $host` to replaces local plantuml server ip with FQDN +- `proxy_set_header X-Forwarded-Proto $scheme` to use reverse proxy protocol schema instead of communication schema between reverse proxy and plantuml server +- `proxy_pass http://plantuml-server:8080/` to set reverse proxy path to plantuml server. + Use the docker container name `plantuml-server` instead of ip addresses. + + +## Nginx and PlantUML server + +```yaml +version: "3" + +services: + plantuml-server: + image: plantuml/plantuml-server:jetty + container_name: plantuml-server + environment: + - TZ="Europe/Berlin" + + nginx: + image: nginx:alpine + container_name: nginx + ports: + - "80:80" + environment: + - TZ="Europe/Berlin" + volumes: + - ./nginx.conf:/etc/nginx/nginx.conf:ro +``` + +- Set `container_name` to use them instead of e.g. ip addresses +- Set the environment `TZ` the ensure the same timezone. + For example to server timezone (`cat /etc/timezone`)? +- plantuml-server + * plantuml-server already exposes port `8080` to it's own local network (but not outside). + Since plantuml-server and nginx are sharing a network, nginx can reach plantuml-server without further settings. +- nginx + * open/link port `80` to the outside + * `./nginx.conf:/etc/nginx/nginx.conf:ro` to use your own Nginx configuration (readonly) + + +## Useful commands + +```bash +# see whats going on inside your docker containers +docker logs --tail 50 --follow --timestamps nginx +docker logs --tail 50 --follow --timestamps plantuml-server +``` diff --git a/examples/nginx-simple/docker-compose.yml b/examples/nginx-simple/docker-compose.yml new file mode 100644 index 0000000..b3b8367 --- /dev/null +++ b/examples/nginx-simple/docker-compose.yml @@ -0,0 +1,18 @@ +version: "3" + +services: + plantuml-server: + image: plantuml/plantuml-server:jetty + container_name: plantuml-server + environment: + - TZ="Europe/Berlin" + + nginx: + image: nginx:alpine + container_name: nginx + ports: + - "80:80" + environment: + - TZ="Europe/Berlin" + volumes: + - ./nginx.conf:/etc/nginx/nginx.conf:ro diff --git a/examples/nginx-simple/nginx.conf b/examples/nginx-simple/nginx.conf new file mode 100644 index 0000000..ceda4f7 --- /dev/null +++ b/examples/nginx-simple/nginx.conf @@ -0,0 +1,48 @@ +user nginx; +worker_processes auto; + +error_log /var/log/nginx/error.log notice; +pid /var/run/nginx.pid; + +include /etc/nginx/modules-enabled/*.conf; + +events { + worker_connections 1024; +} + +http { + + server { + listen 80; + server_name localhost; + + # PlantUML + location / { + proxy_set_header HOST $host; + proxy_set_header X-Forwarded-Host $host; + proxy_set_header X-Forwarded-Proto $scheme; + + proxy_pass http://plantuml-server:8080/; + } + } + + client_max_body_size 0; + + include /etc/nginx/mime.types; + default_type application/octet-stream; + + log_format main '$remote_addr - $remote_user [$time_local] "$request" ' + '$status $body_bytes_sent "$http_referer" ' + '"$http_user_agent" "$http_x_forwarded_for"'; + + access_log /var/log/nginx/access.log main; + + sendfile on; + #tcp_nopush on; + + keepalive_timeout 65; + + #gzip on; + + include /etc/nginx/conf.d/*.conf; +}