Self-hosted server

Breaking changes

Check this list before you upgrade. Most servers only need the backup and upgrade steps in Upgrading from V1.

3.x#

  • 3.4.0: PostScript, EPS, PCL and XPS conversion was removed (/api/v1/convert/pdf/vector, /api/v1/convert/vector/pdf).
  • 3.4.0: fonts in customFiles/static/fonts/ are no longer served at /fonts/. Only the text editor uses them.
  • 3.3.0: the backend text-editing API was removed (/api/v1/general/edit-text, /api/v1/convert/pdf/text-editor and related endpoints).
  • 3.3.0: request bodies sent with Content-Encoding are refused with HTTP 400. Send them uncompressed.
  • 3.3.0: security.ssoAutoLogin redirects to SSO even when password login is on. Open /login?all for the password form.
  • 3.2.0: PDF permission restrictions are enforced unless the permissions password is entered. Set security.honorOwnerPasswords: false to turn this off.

New web interface#

V1 built its pages on the server from templates in customFiles/templates/. V2 is a separate web app, so those templates are ignored.

  • For the app name and logo, use the branding settings in UI and branding.
  • Files in customFiles/static/ still replace built-in files at the same path, but the paths are those of the new app, for example customFiles/static/index.html.
  • For deeper changes you would need to build your own frontend. See Contributing.

Removed and renamed settings#

Some settings were removed or renamed, including ui.appName and the pdf-organizer tool ID. Check Settings changes, especially if you disabled tools with endpoints.toRemove.

Login and Docker images#

  • The latest and latest-fat images always include login and admin features. DOCKER_ENABLE_SECURITY and DISABLE_ADDITIONAL_FEATURES no longer change this; use security.enableLogin (SECURITY_ENABLELOGIN) to turn login on or off.
  • latest-ultra-lite has no login, users or admin settings.
  • New settings files have login on by default. An upgraded server keeps the enableLogin value from its existing settings.yml.
  • Images named s-pdf still get the same builds, but stirlingtools/stirling-pdf is the main name.

Plans and user limits#

  • The Free plan allows 5 users. An upgraded server keeps its current number of users as its limit if that is higher, but can't add users beyond it without Team or Enterprise.
  • SAML sign-in needs Enterprise. Existing single sign-on users keep it.
  • Some admin features need Team or Enterprise. See Plans and licences.
  • Old enterpriseEdition settings in settings.yml move to premium automatically.

Java 25 for the JAR#

The JAR now needs Java 25 instead of Java 17. Docker images include the right Java.

Database#

The built-in and external databases are upgraded in place on first start, so rolling back needs your backup. See Roll back.

API#

API paths still start with /api/v1, and users' API keys carry over. If you generate clients from the OpenAPI spec, regenerate them from /v1/api-docs and test your integrations before switching. See REST API.