High-performance HTTP service for PlantUML, used in Kibela
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
example
gradle/wrapper
src
.gitignore
.travis.yml
Aptfile
CHANGES.md
LICENSE.md
Procfile
README.md
app.json
build.gradle
gradlew
gradlew.bat
release.gradle
settings.gradle
system.properties

README.md

PlantUML HTTP service Build Status

This is a high-performance HTTP interface to PlantUML.

Table of Contents

Install

There's two way to install plantuml-service:

Jar

Get plantuml-service.jar from GitHub releases.

Homebrew Tap

There is a homebrew formula in bitjourney/homebrew-self for macOS:

brew install bitjourney/self/plantuml-service
brew services start bitjourney/self/plantuml-service

Usage

POST /svg where body is the source of PlantUML

Returns an SVG image of the request body, processed by PlantUML.

Because the size of GET requests might be limited by middlewares, the POST API is recommended in production.

GET /svg/:source

Returns an SVG image of :source processed by PlantUML.

:source is source code of PlantUML, encoded in percent encoding.

Example:

Given a PlantUML source code:

@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response
@enduml

To show it in SVG:

![]($ENDPOINT/%40startuml%0AAlice%20-%3E%20Bob%3A%20Authentication%20Request%0ABob%20--%3E%20Alice%3A%20Authentication%20Response%0A%0AAlice%20-%3E%20Bob%3A%20Another%20authentication%20Request%0AAlice%20%3C--%20Bob%3A%20another%20authentication%20Response%0A%40enduml%0A)

Then, you'll get:

This path takes multiple config parameters to set configuration, for example:

/svg/...?config=scale max 1024 width&config=skin BlueModern

NOTE: you should use server-side RPC to render SVG because browsers have URL limitations.

GET /version

Shows the version of PlantUML and plantuml-service in JSON:

{"PlantUML":"2017.11","plantuml-service":"1.0.9"}

This is also intended to check the service helth.

Example:

Development

Run on local:

./gradlew stage && heroku local:start

Deployment

Run on Heroku

Deploy to Heroku:

# build
./gradlew stage

# run
bin/plantuml-service $PORT

Run with systemd

Here is an example systemd.service(5) config file:

[Unit]
Descrption=PlantUML service
Documentation=https://github.com/bitjourney/plantuml-service
Wants=network-online.target
After=network-online.target

[Service]
ExecStart=$APP_PATH/app/bin/plantuml-service
WorkingDirectory=$APP_PATH/app

User=$APP_USER
Group=$APP_USER

[Install]
WantedBy=multi-user.target

Release Engineering

  1. Create the credential file by echo "oauth=$GITHUB_ACCESS_TOKEN" > ~/.github
  2. Update the version of build.gradle
  3. Run ./gradlew release
  4. Update the homebrew fomula (see bitjourney/homebrew-self)

About plantuml-service.herokuapp.com

plantuml-service.herokuapp.com is an example service managed by Bit Journey, Inc..

Because this is an example, there's no guarantee for the availability.

See Also

Authors

  • FUJI Goro (gfx)

License

Copyright (c) 2016 Bit Journey, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.