PdfDing 1.15.0 on AWS User Guide

Overview

This guide covers launching and using the PdfDing 1.15.0 on Ubuntu 24.04 AMI from cloudimg on Amazon EC2. It is one version of the cloudimg documents, forms and scheduling listing on AWS Marketplace; you pick it as the software version when you subscribe and launch.

PdfDing is an open source PDF manager, viewer and editor for your browser. You upload PDFs into workspaces and collections, read them in the built-in viewer (which remembers where you stopped), highlight, comment and add text or drawings, then save the annotated file back. PDFs can be tagged, starred, archived and searched, and any PDF can be shared through a link, optionally protected with a password, a view limit or an expiry.

Upstream PdfDing ships as a container you configure yourself. The cloudimg image installs it natively and adds:

• HTTPS from the first boot. nginx serves PdfDing on port 443 with a certificate generated on your instance's first boot. Port 80 redirects to HTTPS, and requests for host names the instance does not serve are dropped.
• One administrator, a password unique to your instance. There is no default account. First boot creates the administrator admin@pdfding.local with a random password, generates a Django secret key unique to the instance, and checks the sign-in works before nginx opens port 443. Sign-up is closed: the administrator adds users under Admin > Users.
• The patched pdf.js viewer. PdfDing 1.15.0 pins Mozilla pdf.js 6.1.200, which is affected by GHSA-hq66-cqwq-w95j. This image serves the unmodified Mozilla pdf.js 6.2.108 build, the release that fixes it, on the owner's viewer and on share links alike. pdf.js's own scripting sandbox is kept as Mozilla ships it.
• Hardened defaults. The application server (gunicorn) listens on 127.0.0.1:8000 only. The host names and CSRF origins are pinned to the name the instance is served as, sign-in attempts are rate limited per client, uploads are checked to be real PDFs (200 MB per upload), PDFs are always served as application/pdf with nosniff, and request paths with encoded or backslash characters are refused before they reach the application.
• Metadata and private networks blocked. The PdfDing service cannot reach the EC2 instance metadata service, your VPC's own address ranges or other private ranges; the instance requires IMDSv2.
• Patched. The image is fully patched Ubuntu 24.04 LTS with unattended security upgrades on. The Python dependencies are installed from a hash-pinned lock and the PdfDing source from the sha256-pinned 1.15.0 release archive.

What is on the image: PdfDing 1.15.0 (Django, in a Python 3.12 virtual environment under /opt/pdfding), Mozilla pdf.js 6.2.108, nginx, Ubuntu 24.04 LTS, cloud-init and the AWS Systems Manager agent. The licences, the build notes and the source offer are in /usr/share/doc/pdfding/.

Default user: ubuntu · Architecture: x86_64 · Recommended instance type: m5.large

Prerequisites

• An AWS account subscribed to the listing, an EC2 key pair and a VPC subnet with a route to the internet (or a private route you use for management).
• A security group that allows TCP 22 (SSH), TCP 443 (PdfDing) and TCP 80 (redirects to HTTPS). Open 22 from your own networks only; open 443 and 80 to the people who use PdfDing.

Step 1: Launch the instance

In the AWS Marketplace listing choose Continue to Subscribe, then Continue to Configuration, pick PdfDing 1.15.0 on Ubuntu 24.04 as the software version and your Region, then Launch through EC2. Choose m5.large (or larger for many users), your key pair and a security group as above. Give the root volume enough space for the PDFs you plan to store.

With the AWS CLI (replace the values in angle brackets):

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=pdfding}]'

First boot takes under a minute: it generates the secret key, the certificate and the administrator password, creates the database and checks the sign-in before nginx opens port 443.

Step 2: Connect to your instance

ssh -i <your-key.pem> ubuntu@<public-ip>

The message of the day shows where your login details are and the recovery commands.

Step 3: Check the services

Three systemd units run PdfDing: the network egress backstop, the PdfDing application server and nginx.

systemctl is-active pdfding-egress pdfding nginx
sudo ss -Htln | awk '{print $4}' | sort -u

active
active
active
0.0.0.0:22
0.0.0.0:443
0.0.0.0:80
127.0.0.1:8000
127.0.0.53%lo:53
127.0.0.54:53
[::]:22
[::]:443
[::]:80

PdfDing itself listens only on 127.0.0.1:8000; nginx is the only thing on 80 and 443.

Step 4: Get your address and administrator password

First boot writes your login details to a file only root can read. This shows it without the password line:

sudo grep -v '^ADMIN_PASSWORD=' /var/lib/cloudimg/pdfding-credentials.txt

# PdfDing 1.15.0 - generated on this instance's first boot by pdfding-firstboot.service.
# The administrator below is the only account and is unique to this instance; no default account exists.
# PdfDing stores only a PBKDF2 hash of the password. Keep this file secret.
PDFDING_URL=https://ec2-203-0-113-25.compute-1.amazonaws.com/
ADMIN_EMAIL=admin@pdfding.local
#
# Open PDFDING_URL in a browser (self-signed certificate minted on this first boot; port 80 redirects to https) and sign
# in with the e-mail address and password above. Change both under Settings > Account once you are in.
# Sign-up is closed: add users under Admin > Users. Lost access?  sudo pdfding-reset-password
# Change the name it is served as:  sudo pdfding-set-hostname <your-dns-name>
# User guide: https://www.cloudimg.co.uk/guides/pdfding-1-15-0-on-ubuntu-24-04-aws/

To read the password itself, run this on the instance:

sudo grep '^ADMIN_PASSWORD=' /var/lib/cloudimg/pdfding-credentials.txt

Step 5: Sign in

Open the PDFDING_URL address in your browser. The certificate is generated on your instance, so the browser warns until you install a certificate it trusts (Step 8). Sign in with admin@pdfding.local and the password from Step 4. The page still shows upstream's "sign up" link, but sign-up is closed on this image: the sign-up page offers no form and no account can be created from it.

Once you are in, open Settings > Account (the round avatar at the top right) and change the e-mail address and the password to your own.

Step 6: Upload, read and annotate PDFs

Choose + at the top right to add a PDF: give it a name and pick the file (or use bulk add for several). Your PDFs are listed on the PDFs page, newest first; use the workspace and collection selectors on the left to organise them, and tags, stars and the archive to find them again.

Open a PDF to read it in the pdf.js viewer. PdfDing remembers the page you were on. The toolbar on the right has the editing tools: highlight, add text, draw and add images. Choose the save icon to write your annotations back into the stored PDF; highlights and comments are also listed under Annotations in the sidebar.

Step 7: Share a PDF

From a PDF's menu choose Share. Give the share a name and, optionally, a password, a maximum number of views and a time after which it is deleted. PdfDing creates a link (and a QR code) under Shared; anyone with the link can open the PDF in the same patched viewer without an account, after entering the password if you set one.

Share links point at the name the instance is served as, so set your own DNS name (Step 8) before you hand links out.

Step 8: Your own DNS name and certificate

PdfDing accepts requests only for the one name it is served as (the instance's public DNS name at first boot). Point a DNS record at the instance, then:

sudo pdfding-set-hostname pdf.your-domain.example

This pins the new name in PdfDing's allowed hosts and CSRF origins, writes a new self-signed certificate for it and restarts the services. To use a certificate your browsers trust, replace /etc/ssl/pdfding/pdfding.crt and /etc/ssl/pdfding/pdfding.key with your own (or one from your certificate authority) and run sudo systemctl reload nginx.

Step 9: Check the security posture from the command line

These read-only checks show HTTPS, the redirect, the dropped unknown host names, the refused encoded paths, the pdf.js version actually served, the metadata block and the application's network deny list:

H=$(sudo head -n1 /etc/pdfding/served-host); echo "served as: $H"
curl -sk -o /dev/null -w 'https %{http_code}\n' --resolve "$H:443:127.0.0.1" "https://$H/accountlogin/"
curl -s -o /dev/null -w 'http %{http_code}\n' --resolve "$H:80:127.0.0.1" "http://$H/"
curl -sk -o /dev/null -w 'unknown host %{http_code}\n' --resolve "other.example:443:127.0.0.1" https://other.example/ || true
curl -sk -o /dev/null -w 'encoded path %{http_code}\n' --resolve "$H:443:127.0.0.1" "https://$H/static/%2e%2e/x" || true
curl -sk --resolve "$H:443:127.0.0.1" "https://$H/static/pdfjs/build/pdf.mjs" | grep -m1 -o 'pdfjsVersion = [0-9.]*'
curl -s -o /dev/null -w 'IMDSv1 %{http_code}\n' http://169.254.169.254/latest/meta-data/ || true
systemctl show -p IPAddressDeny pdfding | cut -c1-120

served as: ec2-203-0-113-25.compute-1.amazonaws.com
https 200
http 301
unknown host 000
encoded path 400
pdfjsVersion = 6.2.108
IMDSv1 401
IPAddressDeny=240.0.0.0/4 0.0.0.0/8 10.0.0.0/8 100.64.0.0/10 ::/0 172.16.0.0/12 168.63.129.16/32 224.0.0.0/4 169.254.0.0

000 means nginx closed the connection without answering (a request for a name the instance does not serve). 401 means the instance metadata service requires IMDSv2 tokens. The deny list is the static part of the egress backstop; your VPC's own address ranges are added at every boot.

The built-in self-test signs in over HTTPS with the administrator account and checks the version and the viewer:

sudo pdfding-selftest 2>&1 | tail -1

round-trip OK: admin@pdfding.local signed in over https://ec2-203-0-113-25.compute-1.amazonaws.com/ (wrong password refused), the app reports v1.15.0 and serves pdf.js 6.2.108, anonymous sent to /accountlogin/, sign-out ended the session

Step 10: Users, e-mail and optional settings

Add users under Admin > Users (the administrator's avatar menu). If you lose the administrator password, or lock the account out with failed sign-ins or a lost second factor, reset it from SSH:

sudo pdfding-reset-password                       # new random password for admin@pdfding.local
sudo pdfding-reset-password someone@example.com   # or for another account (re-created if it was deleted)

The new password is written to /var/lib/cloudimg/pdfding-credentials.txt and never printed.

Optional features are set in /etc/pdfding/pdfding.env: an SMTP relay for password-reset e-mails (without one, those mails go to the service journal, sudo journalctl -u pdfding), OpenID Connect sign-in and the default theme. Security settings are pinned by the image and are not read from this file:

sudo sed -n '1,6p' /etc/pdfding/pdfding.env

# PdfDing optional settings (cloudimg). Read by pdfding.service at start: sudo systemctl restart pdfding
# Security settings (SECRET_KEY, DEBUG, ALLOWED_HOSTS/CSRF, cookies, the database) are pinned by
# /opt/pdfding/app/core/settings/cloudimg.py and are NOT read from here.
# Sign-up stays closed unless you set this to FALSE (the administrator creates accounts under Admin > Users).
DISABLE_USER_SIGNUP=TRUE
# DEFAULT_THEME=system          (light | dark | system)

Edit it with sudo nano /etc/pdfding/pdfding.env, then sudo systemctl restart pdfding.

Step 11: Data and backups

The database, the uploaded PDFs and the per-instance secret key live under /var/lib/pdfding:

sudo ls -la /var/lib/pdfding
ls /usr/share/doc/pdfding

total 8
drwxr-x---  5 root    pdfding  120 Nov  9 22:43 .
drwxr-xr-x 49 root    root    4096 Nov  9 22:41 ..
drwx------  2 pdfding pdfding   40 Nov  9 22:43 consume
drwx------  2 pdfding pdfding   80 Nov  9 22:59 db
drwx------  3 pdfding pdfding   60 Nov  9 22:50 media
-rw-r-----  1 root    pdfding   81 Nov  9 22:43 secret_key
CHANGELOG.md
LICENSE
LICENSE.pdfjs
README.md
SECURITY-NOTES.txt
SECURITY.md
SHA256SUMS
SOURCE-OFFER.txt
THIRD-PARTY-NOTICES.txt
package-lock.json
pdfjs-licenses
poetry.lock

Snapshot the instance's EBS volume to back up everything, or copy /var/lib/pdfding to other storage on a schedule (stop PdfDing first for a consistent copy: sudo systemctl stop pdfding, copy, sudo systemctl start pdfding). Keep backups private: they hold every stored PDF and the secret key that signs sessions and share links.

Step 12: Security recommendations

• Allow port 22 in the security group from your own networks only, and ports 443 and 80 only to the people who use PdfDing.
• Set your DNS name and a trusted certificate before you share links (Step 8).
• Change the administrator's e-mail address and password after the first sign-in, and turn on a second factor under Settings > Account.
• Use share passwords, view limits and expiry times for anything sensitive, and delete shares you no longer need under Shared.
• Keep the operating system patched; unattended security upgrades are on, and sudo apt-get update && sudo apt-get upgrade applies everything else.

Support and licensing

PdfDing is free software under the GNU Affero General Public License, version 3. The complete corresponding source of the version on the image is the PdfDing 1.15.0 release archive named, with its sha256, in /usr/share/doc/pdfding/SOURCE-OFFER.txt. Mozilla pdf.js is under the Apache License 2.0 (LICENSE.pdfjs); the Poppins font is under the SIL Open Font License 1.1; these and the other third-party notices are in /usr/share/doc/pdfding/. There is no per user or per document fee. cloudimg is not affiliated with or endorsed by the PdfDing project or Mozilla; the AMI price covers cloudimg's build, hardening, first boot setup and support.

• Email: support@cloudimg.co.uk
• Website: https://www.cloudimg.co.uk
• Support: 24/7, with a 24 hour response SLA