pp.server 2.0.6.8

pp.server - Produce & Publish Server

pp.server is a Pyramid based server implementation and implements the server side functionality of the Produce & Publish platform. It is known as the Produce & Publish Server.

The Produce & Publish Server provided web service APIs for converting HTML/XML + assets to PDF using one of the following external PDF converters:

• PrinceXML (www.princexml.com, commercial)

• PDFreactor (www.realobjects.com, commercial)

• PhantomJS (free, unsupported)

• Speedata Publisher (www.speedata.de, open-source, experimental support)

• WKHTMLTOPDF (www.wkhtmltopdf.org, open-source, experimental support)

• Vivliostyle Formatter (www.vivliostyle.com, commercial, experimental support)

• VersaType Formatter (www.trim-marks.com, commercial, experimental support)

• Antennahouse 6.6 (www.antennahouse.com, commercial)

• Weasyprint (free, unsupported)

In addition there is experimental support for generating EPUB documents using Calibre (www.calibre.org, open-source).

In addition the Produce & Publish server provides a simple conversion API for converting format A to B (as supported through LibreOffice or OpenOffice). The conversion is build on top of unoconv.

The web service provides only synchronous operation.

Requirements

• Python 3.6 or higher, no support for Python 2.x

• the external binaries

  • PrinceXML: prince,

  • PDFreactor up to version 7: pdfreactor,

  • PDFreactor version 8 or higher: pdfreactor.py,

  • Unoconv: unoconv

  • Speedata Publisher: sp

  • Calibre: ebook-convert

  • WKHTMLTOPDF: wkhtmltopdf

  • Vivliostyle: vivliostyle-formatter

  • VersaType : versatype-converter

  • Weasyprint: weasyprint

  • Antennahouse: run.sh

  must be in the $PATH. Please refer to the installation documentation of the individual products.

Installation

• create a Python 3 virtual environment using:

  python3 -m venv pp.server

• install the Produce & Publish server:

  bin/pip install pp.server

• create a server.ini configuration file (and change it according to your needs):

  [DEFAULT]
  debug = true
  
  [app:main]
  use = egg:pp.server
  reload_templates = true
  debug_authorization = false
  debug_notfound = false
  
  [server:main]
  use = egg:gunicorn#main
  host = 0.0.0.0
  port = 6543
  
  
  
  [loggers]
  keys = root, myproject
  
  [handlers]
  keys = console, logfile
  
  [formatters]
  keys = generic, form01
  
  [formatter_form01]
  format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
  datefmt=
  class=logging.Formatter
  
  [logger_root]
  level = INFO
  handlers = console, logfile
  
  [logger_myproject]
  level = DEBUG
  handlers =
  qualname = myproject
  
  
  [handler_console]
  class = StreamHandler
  args = (sys.stderr,)
  level = NOTSET
  formatter = form01
  
  [handler_logfile]
  class = FileHandler
  level = INFO
  formatter = form01
  args=('var/gunicorn.log', 'w')
  
  [formatter_generic]
  format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s

• create a circusd.ini configuration file (and change it according to your needs):

  [watcher:gunicorn]
  cmd = bin/gunicorn --paste server.ini
  
  [env:gunicorn]
  PATH = $PATH
  TZ = $TZ

• both configuration files can be created automatically using the helper script:

  bin/pp-server-templates

• start the server (in foreground):

  bin/gunicorn --paste server.ini

• or start it in background:

  bin/circusd circusd.ini  --daemon

Converter requirements

For the PDF conversion the related converter binaries or scripts must be included in the $PATH of your server.

• prince for PrinceXML

• pdfreactor for PDFreactor 7

• pdfreactor8 for PDFreactor 8 or higher

• phantomjs for PhantomJS

• wkhtmltopdf for WKHTMLToPDF

• ebook-convert for Calibre

• sp for the Speedata Publisher

• vivliostyle for the Vivliostyle formatter

• versatype for the Versatype converter

• weasyprint for Weasyprint

• antennahouse for the Antennahouse

API documentation

All API methods are available through a REST api following API URL endpoint:

http://host:port/api/1/<command>

With the default server configuration this translates to:

http://localhost:6543/api/1/pdf

or

http://localhost:6543/api/1/unoconv

Environment variables

pp.server uses the var folder of the installation directory by default as temporary folder for conversion data. Set the environment variable PP_SPOOL_DIRECTORY if you need different spool directory instead.

If you run PDFreactor 10 or higher under Docker then you must set the environment variable PP_PDFREACTOR_DOCKER=1 in order to generated a proper file:///docs/… URI for pdfreactor.py.

PDF conversion API

Remember that all converters use HTML or XML as input for the conversion. All input data (HTML/XML, images, stylesheets, fonts etc.) must be stored in ZIP archive. The filename of the content must be named index.html.

You have to POST the data to the

http://host:port/api/1/pdf

with the following parameters:

• file - the ZIP archive (multi/part encoding)

• converter - a string that determines the the PDF converter to be used (either princexml, pdfreactor, phantomjs, vivliostyle, versatype, or calibre for generating EPUB content)

• cmd_options - an optional string of command line parameters added as given to the calls of the externals converters

Returns:

The API returns its result as JSON structure with the following key-value pairs:

• status - either OK or ERROR

• data- the generated PDF file encoded as base64 encoded byte string

• output - the conversion transcript (output of the converter run)

Unoconv conversion API

The unoconv web service wraps the OpenOffice/LibreOffice server mode in order to perform document conversion (mainly used in the Produce & Publish world for convertering DOC(X) documents to HTML/XML).

Remember that all converters use HTML or XML as input for the conversion. All input data (HTML/XML, images, stylesheets, fonts etc.) must be stored in ZIP archive. The filename of the content must be named index.html.

You have to POST the data to the

http://host:port/api/1/unoconv

with the following parameters:

• file - the source files (multi/part encoding)

• cmd_options - an optional string of command line parameters added as given to the unoconv calls

Returns:

The API returns its result as JSON structure with the following key-value pairs:

• status - either OK or ERROR

• data - the converted output files as ZIP archive (e.g. a DOCX file containing images will be converted to a HTML file plus the list of extract image files)

• output - the conversion transcript (output of the converter run)

Introspection API methods

Produce & Publish server version:

http://host:port/api/version

returns:

{“version”: “0.3.2”, “module”: “pp.server”}

Installed/available converters:

http://host:port/api/converters

returns:

{“unoconv”: true, “pdfreactor”: true, “phantomjs”: false, “calibre”: true, “princexml”: true}

Versions of installed converter:

http://host:port/api/converter-versions

returns:

{‘princexml’: ‘Version x.y’, ‘pdfreactor: ‘Version a.b.c’, …}

Other API methods

Cleanup of the queue directory (removes conversion data older than one day)

http://host:port/api/cleanup

returns:

{“directories_removed”: 22}

Advanced installation issues

Installation of PDFreactor using zc.buildout

• https://bitbucket.org/ajung/pp.server/raw/master/pdfreactor.cfg

Installation of PrinceXML using zc.buildout

• https://bitbucket.org/ajung/pp.server/raw/master/princexml.cfg

• https://bitbucket.org/ajung/pp.server/raw/master/circus-app.ini

Source code

https://bitbucket.org/ajung/pp.server

Bug tracker

https://bitbucket.org/ajung/pp.server/issues

Support

Support for Produce & Publish Server is currently only available on a project basis.

License

pp.server is published under the GNU Public License V2 (GPL 2).

Contact

ZOPYX

Hundskapfklinge 33

D-72074 Tuebingen, Germany

[e-mail]

www.zopyx.com

www.produce-and-publish.info

2.0.4 (2019/02/11)

• minor installation issues with var folder gunicorn.log

• added optional PP_PDFREACTOR_DOCKER environment support

2.0.3 (2019/02/11)

• minor installation issues with var folder gunicorn.log

• added optional PP_SPOOL_DIRECTORY environment support

2.0.0 (2018/07/14)

• major cleanup

• removed async functionality

• switched from waitress to gunicorn

• switched from subprocess to easyprocess

• webpage displays installed converters and their versions

• support for VersaType converter added

1.0.8 (2017/10/23)

• internal release

1.0.7 (2017/08/17)

• fixed a very old bug in cleanup code

1.0.6 (2017/08/08)

• display available converters during startup

1.0.5 (2017/04/06)

• support for WeasyPrint

1.0.3 (2017/02/13)

• calling princexml with explicit option -o (Prince 11 compatibility)

1.0.0 (2017/01/08)

• first official release

• requires Python 3.5 or higher

0.7.13 (2016/08/30)

• added circus dependency in order to provide daemonizing support out of the box

0.7.12 (2016/08/29)

• fix for PDFreactor 8

0.7.11 (2016/06/01)

• updated to Pyramid 1.7

0.7.7 (2016/01/24)

• updated support for latest Vivliostyle formatter

• added support for Antennahouse Formatter

0.7.6 (2015/11/30)

• support for PDFreactor 8

0.7.5 (2015/11/18)

• fixed race condition while creating directories

0.7.4 (2015/11/14)

• support for nested uploaded ZIP files

0.7.3 (2015/11/14)

• support for Vivliostyle Formatter

0.7.2 (2015/04/20)

• merged https://bitbucket.org/ajung/pp.server/pull-request/1/ (improper check for wkhtmltopdf)

• merged https://bitbucket.org/ajung/pp.server/pull-request/2/ (fix for async operations)

0.7.1 (2015/03/13)

• unicode fix in runcmd()

0.7.0 (2015/02/15)

• 0.6.x was completely badly packaged

• changed repo structure

0.6.1 (2015/02/02)

• add /api/converter-versions to webservice API

0.6.0 (2015/01/26)

• dropped Python 2.X support, Python 3.3 or higher is now a mandatory requirement

0.5.5 (2015/01/23)

• UTF8 handling fix

0.5.3 (2014/11/23)

• support for WKHTMLTOPDF

0.5.2 (2014/11/19)

• support for Speedata Publisher

0.5.1 (2014/10/12)

• improved error handling

0.5.0 (2014/10/12)

• official Python 3.3/3.4 support

0.4.7 (25.09.2014)

• fixed documentation bug

0.4.6 (22.08.2014)

• removed PDFreactor –addlog option

0.4.5 (22.08.2014)

• added supplementary commandline options to pdfreactor commandline call

0.4.4 (24.01.2014)

• minor typos fixed

0.4.3 (20.01.2014)

• implemented automatic queue cleanup after one day

0.4.2 (18.01.2014)

• URL fix in index.pt related to virtual hosting

0.4.1 (13.01.2014)

• show Python version and converters on index.pt

• authorization support added

0.4.0 (17.10.2013)

• Python 3.3 support

• Pyramid 1.5 support

0.3.5 (05.10.2013)

• added ‘cmd_options’ to pdf and unoconv API methods for specifying arbitary command line parameters for the external converters

0.3.4 (05.10.2013)

• added ‘cleanup’ API

0.3.3 (05.10.2013)

• added ‘version’ and ‘converter’ API methods

0.3.2 (04.10.2013)

• added support EPUB conversion using Calibre

0.3.1 (03.10.2013)

• updated documentation

0.3.0 (14.07.2013)

• unoconv conversion now returns a ZIP archive (e.g. a HTML file + extracted images)

0.2.7 (06.07.2013)

• added support for Phantom.js converter

0.2.5 (05.07.2013)

• better detecting of prince and pdfreactor binaries

0.2.2 (05.07.2013)

• updated the documentation

• minor cleanup

0.2.1 (04.07.2013)

• re-added poll API

0.2.0 (03.07.2013)

• converted XML-RPC api to REST api

0.1.9 (01.07.2013)

• monkeypatch pyramid_xmlrpc.parse_xmlrpc_request in order to by-pass its stupid DOS request body check

0.1.7 (29.06.2013)

• more tests

• fixes

• updated documentation

0.1.5 (27.06.2013)

• test for synchronous operations

• fixes

0.1.0 (24.06.2013)

• initial release