Go JavaScript Makefile Shell
Switch branches/tags
Clone or download
Latest commit eabbc98 Jul 5, 2018

README.md

Athena

Build Status License Gitter chat

Live Demo / Screenshots

WARNING: VERSION 2 IS NO LONGER MAINTAINED; PIN ALL USES OF IT

Simple, Docker-powered PDF conversions.

Athena is comprised of an Electron command line interface (CLI) tool, and a Go microservice for converting HTML to PDF documents.

Athena transformed Arachne into a spider for challenging her as a weaver and/or weaving a tapestry that insulted the gods.

Examples:

When aggressive mode is enabled, only the essential contents of a page are kept in the generated PDF document. It is a clutter-free version of the web page, perfect for reading.

Background

Athena is an open source project.

It was designed to do one thing and to do it well - PDF conversions; to work together with other programs; and to be able to handle text streams, because that is a universal interface.

It aims to give users an on-demand capability to convert HTML to PDF without frills.

At the lowest level, its CLI component (athenapdf) was designed to be an alternative / drop-in replacement for wkhtmltopdf, a popular CLI tool for HTML to PDF conversions. Because of Docker the CLI syntax is a bit more complex but it's much more reliable.

(For what it's worth, wkhtmltopdf is great, but it has a horrible habit of crashing unexpectedly - especially when printing documents with invalid HTML, problematic CSS or other issues).

There is also a microservice component (weaver), allowing you to leverage Athena over HTTP.

Getting Started

CLI vs Microservice

Our CLI tool will suffice for most simple, and everyday HTML to PDF conversions.

However, for conversions at scale / PDF conversion as a service, we recommend getting started with our microservice component instead.

CLI vs Microservice

The microservice is packaged with athenapdf, and you can run both components independently.

Docker

Both components are packaged, and distributed as Docker images.

The only dependency you will need is Docker, and the rest will be handled for you (even if you are running in an environment without a display server - headless environment).

Quick Start

Before starting, ensure your Docker environment is set up, and ready-to-use.

For OSX / Windows users, ensure your Docker Machine is prepared, and the appropriate environment variables are established.

CLI

asciicast

  1. docker pull arachnysdocker/athenapdf
  2. docker run --rm -v $(pwd):/converted/ arachnysdocker/athenapdf athenapdf <input_path> [output_path]
  3. See cli for full documentation

The [output_path] can be omitted.

Example: docker run --rm -v $(pwd):/converted/ arachnysdocker/athenapdf athenapdf http://blog.arachnys.com/

For Windows users, an additional forward slash must precede the volume when using Git Bash / MinGW:

docker run --rm -v /$(pwd):/converted/ arachnysdocker/athenapdf athenapdf http://blog.arachnys.com/

Alternatively, if using the Windows command prompt:

docker run --rm -v %cd%:/converted/ arachnysdocker/athenapdf athenapdf http://blog.arachnys.com/

Microservice

asciicast

  1. docker pull arachnysdocker/athenapdf-service
  2. docker run -p 8080:8080 --rm arachnysdocker/athenapdf-service
  3. Inline conversion: http://<docker-address>:8080/convert?auth=arachnys-weaver&url=http://blog.arachnys.com/
  4. OR cURL, and redirect output to file: curl http://dockerhost:8080/convert\?auth\=arachnys-weaver\&url\=http://blog.arachnys.com/ |> out.pdf
  5. See weaver for full documentation

The default authentication key is arachnys-weaver. This can be changed through the WEAVER_AUTH_KEY environment variable.

The microservice can be deployed scalably to ECS if you want to build your own conversion farm.

License

Please note athenapdf is NEITHER affiliated with NOR endorsed by Google Inc. and GitHub Inc.

See LICENSE.


Arachnys

An Arachnys Christmas project.