PdfMage

PdfMage is a standalone microservice packaged as a Ruby gem that makes it simple to render PDFs by using a headless Chrome instance on a standalone server.

It includes support for:

• Uploading PDFs to AWS S3
• Webhooks
• API "secrets" for security

Please note, the documentation is still in-progress!

Running the Server

To run the server, you need to start both the API and the Sidekiq job server. If running in production, make sure to enable the environment flag for it, or else it'll default to the development environment:

PDFMAGE_ENV=production bin/pdf_mage
PDFMAGE_ENV=production bin/sidekiq

We recommend using a service such as monit to keep these processes alive in production, as system issues could cause them to crash and not be restarted.

The config file must also be defined when starting the server, e.g. if your config file is named config.yml.local, pass CONFIG_FILE=config.yml.local:

CONFIG_FILE=config.yml.local bin/pdf_mage
CONFIG_FILE=config.yml.local bin/sidekiq

(For more on the config files, see the 'Configuration' section and 'Appendix A')

Installation

Clone the repository to your computer and navigate to the directory:

git clone https://github.com/sideqik/pdf-mage.git
cd pdf-mage

Then install bundler if you haven't already done so:

gem install bundler

Finally, run the setup command:

bin/setup

On MacOSX, the ps2pdf command must be available. To install via Homebrew:

brew install ghostscript

Configuration

Note: As written, these instructions are meant for developers setting-up a local server.

Also note: "sidekiq" refers to the sidekiq gem, while "sideqik" refers to the sideqik web app.

Add these aliases to your terminal shell's config file (on a Mac, that will probably be ~/.bashrc or ~/.zshrc). Technically you don't need these, but they'll make it a lot easier to start the server when the time comes:

alias pdf-mage-start="PDFMAGE_ENV=development CONFIG_FILE=config.yml.local SIDEKIQ_CONCURRENCY=1 bin/pdf_mage"
alias pdf-mage-start-2="PDFMAGE_ENV=development CONFIG_FILE=config.yml.local SIDEKIQ_CONCURRENCY=1 bin/sidekiq_dev"

In the project root directory, Create a config.yml.local file and overwrite any of the following properties (you can see the default config.yml file at lib/pdf_mage/config.yml).

Note: If you are a Sideqik developer, see 'Appendix A' for specific instructions re: config files.

In the project, add this to the bin/sidekiq_dev file:

PDFMAGE_ENV=development bundle exec sidekiq -r ./lib/pdf_mage_workers.rb -q pdfmage -c $SIDEKIQ_CONCURRENCY

You may have to run chmod 777 on this file, e.g.: sudo chmod 777 bin/sidekiq_dev

Don't forget to run yarn install in both the project root directory and the print-to-pdf directory. This works with Node version 15.3 (it may work with other Node versions as well).

To start the server, open two terminal tabs in the project root directory. In one tab, run pdf-mage-start, and in the other, run pdf-mage-start-2 (these are the aliased commands from the start of this section).

Using the "Secret" for Security

If you use the API secret config option, you can add security to your application. Adding a secret will:

1. Require you to pass a "secret" param with every request to PDF Mage's render resource, where the value is the secret set in the config.
2. Request the website url you want PDF Mage to render with a "secret" parameter, with the value you set in the config.
3. Sign the webhook sent to your server with a SHA256 hexdigest as an "X-Export-Signature" header. See info about checking the signature below.

To check the X-Export-Signature header:

1. Create a SHA256 HMAC hexdigest using the config secret as the key and the response body as the data.
2. Compare the hexdigest to the signature provided.

Example in Ruby:

# Generate the signature that should have been returned
valid_signature = OpenSSL::HMAC.hexdigest('sha256', CONFIG.api_secret, response.body)

# Compare the signatures
response.headers['X-Export-Signature'] == valid_signature

Development

After checking out the repo, run bin/setup to install dependencies. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/sidekiq/pdf_mage. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the PdfMage project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Appendix A

Config file setup for Sideqik devs

Note that you'll need several private keys from Sideqik to get this working - for these, reach out to your team lead or other devs.

Edit the /lib/pdf_mage/config.yml file to have the following settings.

Note: this includes one private key (convertapi_secret).

api_secret: null
aws_account_key: null
aws_account_bucket: null
aws_account_region: 'us-east-1'
aws_account_secret: null
chrome_exe: chrome
log_level: 'info'
delete_file_on_upload: true
export_directory: 'pdfs'
optimize_pdf_size: true
convertapi_secret: <private>
# Render configurations
#configs:
#  javascript_render:
#    run_all_compositor_stages_before_draw: true
#    virtual_time_budget: 10000

In the project root directory, create a config.yml.local file with the following settings.

Note: this includes three private keys (api_secret, aws_account_key, aws_account_secret).

Also note: the value for chrome_exe should be the path to your Chrome executable, which may be different than the value here.

api_secret: <private>
aws_account_key: <private>
aws_account_bucket: sideqik-development
aws_account_region: us-east-1
aws_account_secret: <private>
chrome_exe: /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome
log_level: 'DEBUG'
delete_file_on_upload: false
pdf_directory: 'pdfs'