PdfMage
PdfMage is a standalone microservice packaged as a Ruby gem that you makes it simple to render PDFs using Headless Chrome 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!
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
Running the Server
To run the server, you need to turn run 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.
Configuration
Create a config.yml.local file and overwrite any of the following properties:
name | type | description |
---|---|---|
api_secret | String | TBD |
aws_account_key | String | Key in your AWS S3 API credentials |
aws_account_bucket | String | Bucket to upload PDFs into |
aws_account_region | String | Region to upload PDFs into |
aws_account_secret | String | Secret in your AWS S3 API credentials |
aws_presigned_url_duration | Integer | How long the returned URL in the presigned-request should exist for, in seconds |
chrome_exe | String | Path to the Chrome executable |
delete_file_on_upload | Boolean | Whether or not to delete PDFs after they're uploaded |
log_level | String | What level of logs to write to the logfile |
pdf_directory | String | Where to locally store PDFs |
Then, when starting the server, pass CONFIG_FILE=config.yml.local
.
CONFIG_FILE=config.yml.local bin/pdf_mage
CONFIG_FILE=config.yml.local bin/sidekiq
Using the "Secret" for Security
If you use the API secret config option, you can add security to your application. Adding a secret will:
- 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.
- Request the website url you want PDF Mage to render with a "secret" parameter, with the value you set in the config.
- Sign the webhook sent to your server with a SHA256 hexdigest as a "X-Pdf-Signature" header. See info about checking the signature below.
To check the X-Pdf-Signature header:
- Create a SHA256 HMAC hexdigest using the config secret as the key and the response body as the data.
- 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-Pdf-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.