Installing MyPDF for your organisation

MyPDF for organisations runs on one server that you control, at an address such as https://app.yourcompany.com. This guide summarises the installation for the IT administrator. The release also contains the full installation guide (docs/INSTALL.md), an administrator guide and a security overview.

Requirements

A virtual machine at any cloud provider or in your own data centre works. If outbound traffic must go through a web proxy, set OUTBOUND_HTTPS_PROXY in .env.

DNS

Create a DNS A record for the address people will use, for example app.yourcompany.com, pointing to the server's public IP address. With the built-in proxy, the record must be in place before you install, because Let's Encrypt checks it to issue the HTTPS certificate. If the address also has an AAAA (IPv6) record, it must point to the same server, or be removed.

dig +short app.yourcompany.com     # should print your server's IP address

Proxy modes

A reverse proxy receives HTTPS connections from browsers, holds the certificate and passes requests to MyPDF. Choose one of three modes:

Whatever proxy you use, it must keep the original Host header, send X-Forwarded-Proto: https, allow uploads of 210 MB and requests of up to 15 minutes, not buffer responses under /ai/ (AI replies are streamed), and leave /social/m/… reachable from the internet without a login (Instagram downloads images from there). The full guide has ready-made nginx and Caddy settings, and notes for Traefik v3 time-outs and Cloudflare's upload limits.

Install

Copy the release to the server, unzip it and run the installer as root:

unzip mypdf-1.0.0.zip
cd mypdf-1.0.0
sudo ./install.sh

The installer asks for the address, the proxy mode (it suggests one), an email address for Let's Encrypt notices (built-in proxy only), and optionally your licence key and email server. You can also give everything as options:

# built-in proxy with Let's Encrypt
sudo ./install.sh --domain app.yourcompany.com --email it@yourcompany.com --proxy bundled --yes

# join the Traefik you already run
sudo ./install.sh --domain app.yourcompany.com --proxy traefik \
     --traefik-network traefik --traefik-entrypoint websecure --traefik-certresolver letsencrypt

# behind your own proxy or load balancer
sudo ./install.sh --domain app.yourcompany.com --proxy none --http-port 8080

What it does:

1. Checks the operating system, memory, disk and Docker, and offers to install Docker if it's missing.
2. Checks the ports (built-in proxy) or your Traefik network, and that the address points to this server.
3. Writes the settings to .env (readable by root only), with a new random SECRET_KEY and a one-time set-up token.
4. Builds MyPDF (5–15 minutes the first time), starts it and waits until every part is healthy.
5. Prints the set-up link for the first owner account.

Running the installer again is safe: it keeps your settings, takes a backup first and upgrades in place. To change a setting, run it again with the new option, for example --proxy none. ./install.sh --dry-run … shows what it would do without changing anything, and ./install.sh --help lists every option.

First sign-in with the set-up link

At the end, the installer prints a link like this:

https://app.yourcompany.com/console/setup?token=3f9c…

Open it and create the owner account: name, work email, a strong password and your organisation's name. The link works only until the first account exists, so treat it like a password. If you lose it, sudo scripts/setup-link.sh prints it again.

Then carry on with the set-up checklist in the admin guide: licence, 2-step verification, branding, AI, social apps and inviting your colleagues. People sign in at https://app.yourcompany.com/console/login, and the editor is at https://app.yourcompany.com/.

Email

MyPDF emails invitations, password-reset links and alerts for administrators, such as a social post that failed. Without email everything still works, but admins copy invitation and reset links by hand. Set it during installation, or later:

sudo ./install.sh --smtp-host smtp.office365.com --smtp-user mypdf@yourcompany.com --smtp-from "MyPDF <mypdf@yourcompany.com>"

You're asked for the password. Microsoft 365 needs Authenticated SMTP turned on for that mailbox; Google Workspace needs an app password or its SMTP relay. Many cloud providers block port 25, so use 587 or 465.

Backups

sudo scripts/backup.sh                  # back up now, into backups/
sudo scripts/install-backup-cron.sh     # every night at 02:30, keeping 14 archives

A backup holds the databases (people, settings, audit log, AI settings, social posts), uploaded files and .env, which includes SECRET_KEY. Treat backups as secrets: copy them off the server to encrypted, access-controlled storage, and keep at least one recent copy away from the server. Documents edited in the editor aren't on the server, so they aren't in backups.

To restore (this replaces all MyPDF data, after taking a safety backup):

sudo scripts/restore.sh backups/mypdf-app.yourcompany.com-20261001-023000.tar.gz

To move to a new server, install the same release there with the same address, copy the archive over, restore it, then change the DNS record.

Updates

• Security updates (monthly is a good rhythm): sudo scripts/update.sh rebuilds MyPDF on the latest base images, restarts it and checks its health. It takes a backup first.
• New MyPDF releases: unzip the new release next to the old one, copy your .env (and backups/) across, and run sudo scripts/update.sh. The release's upgrading guide has the details.
• Keep the operating system updated as usual; Docker restarts MyPDF after a reboot.

Everyday commands

Run these from the MyPDF folder:

If something goes wrong

Start with sudo scripts/status.sh, then the logs of the part that isn't healthy. Common causes:

• No certificate (built-in proxy): the A record doesn't point to the server yet, an AAAA record points elsewhere, port 80 is blocked, or Cloudflare proxying is on. Fix it and run sudo docker compose restart mypdf-proxy.
• Large uploads fail: a proxy in front has a smaller upload limit or a shorter time-out.
• AI answers arrive all at once: a proxy in front is buffering /ai/.
• Single sign-on says “redirect URI mismatch”: the address registered with your identity provider must be exactly https://app.yourcompany.com/auth/sso/callback.
• 2-step codes are always rejected: the server's clock is wrong. Check it with timedatectl.

Still stuck? Contact us with the output of sudo scripts/status.sh and the relevant log lines. Never send .env or backups.