diff --git a/docs/Configuration/External Database.md b/docs/Configuration/External Database.md index 2ebb3432..ba2e2030 100644 --- a/docs/Configuration/External Database.md +++ b/docs/Configuration/External Database.md @@ -26,7 +26,7 @@ You can configure the new `Datasource` property in your `settings.yml` to connec ```yaml datasource: enableCustomDatabase: false - customDatabackendUrl: jdbc:postgresql://localhost:5432/postgres + customDatabaseUrl: jdbc:postgresql://localhost:5432/postgres username: postgres password: postgres type: postgresql @@ -36,7 +36,7 @@ You can configure the new `Datasource` property in your `settings.yml` to connec ``` - `enableCustomDatabase`: Set this property to `true` to enable use of the custom database **Note: An enterprise license to use this feature** -- `customDatabackendUrl`: Enter the database connection url for the database here. **Note: If you set the `customDatabackendUrl` you do not need to set the type, hostName, port and name, they will all be automatically derived from the url.** +- `customDatabaseUrl`: Enter the database connection url for the database here. **Note: If you set the `customDatabaseUrl` you do not need to set the type, hostName, port and name, they will all be automatically derived from the url.** - `username`: The username for the database - `password`: The password for the database @@ -80,7 +80,7 @@ services: environment: DISABLE_ADDITIONAL_FEATURES: "false" "true" SYSTEM_DATASOURCE_ENABLECUSTOMDATABASE: "true" - SYSTEM_DATASOURCE_CUSTOMDATABACKENDURL: "jdbc:postgresql://db:5432/stirling_pdf" + SYSTEM_DATASOURCE_CUSTOMDATABASEURL: "jdbc:postgresql://db:5432/stirling_pdf" SYSTEM_DATASOURCE_USERNAME: "admin" SYSTEM_DATASOURCE_PASSWORD: "stirling" # further configuration @@ -89,7 +89,7 @@ services: - `depends_on`: This specifies any services that your app will need in order to run. Ensure the name matches the container name for your database - `DISABLE_ADDITIONAL_FEATURES`: Set this to `false` to enable security features - `SYSTEM_DATASOURCE_ENABLECUSTOMDATABASE`: An environment variable to connect to the database container. Set this to `true` to enable use of the external database -- `SYSTEM_DATASOURCE_CUSTOMDATABACKENDURL`: An environment variable to connect to the database container. Set the connection url for the database here. **Note: If you set this url you do not need to set the type, hostName, port and name (namely `SYSTEM_DATASOURCE_TYPE`, `SYSTEM_DATASOURCE_HOSTNAME`, `SYSTEM_DATASOURCE_PORT`, `SYSTEM_DATASOURCE_NAME`), they will all be automatically derived from the url.** +- `SYSTEM_DATASOURCE_CUSTOMDATABASEURL`: An environment variable to connect to the database container. Set the connection url for the database here. **Note: If you set this url you do not need to set the type, hostName, port and name (namely `SYSTEM_DATASOURCE_TYPE`, `SYSTEM_DATASOURCE_HOSTNAME`, `SYSTEM_DATASOURCE_PORT`, `SYSTEM_DATASOURCE_NAME`), they will all be automatically derived from the url.** - `SYSTEM_DATASOURCE_USERNAME`: An environment variable to connect to the database container. Set the username for the database. Ensure this matches the corresponding property in your database container - `SYSTEM_DATASOURCE_PASSWORD`: An environment variable to connect to the database container. Set the password for the database. Ensure this matches the corresponding property in your database container @@ -103,7 +103,7 @@ services: environment: DISABLE_ADDITIONAL_FEATURES: "false" "true" SYSTEM_DATASOURCE_ENABLECUSTOMDATABASE: "true" - SYSTEM_DATASOURCE_CUSTOMDATABACKENDURL: "jdbc:postgresql://db:5432/stirling_pdf" + SYSTEM_DATASOURCE_CUSTOMDATABASEURL: "jdbc:postgresql://db:5432/stirling_pdf" SYSTEM_DATASOURCE_USERNAME: "admin" SYSTEM_DATASOURCE_PASSWORD: "stirling" # further configuration diff --git a/docs/Configuration/Extra-Settings.md b/docs/Configuration/Extra-Settings.md index 95846b9c..c3f1287a 100644 --- a/docs/Configuration/Extra-Settings.md +++ b/docs/Configuration/Extra-Settings.md @@ -44,8 +44,39 @@ server: max: 200 # Maximum number of request processing threads min: 10 # Minimum number of threads always kept running connection-idle-timeout: 30000 # Connection idle timeout in milliseconds + max-http-request-header-size: 65536 # Maximum size of request headers in bytes ``` +### HTTP 431 "Request Header Fields Too Large" during SSO/OAuth login + +Some SSO/OAuth providers send very large request headers (for example, large cookies or JWTs), which can trigger an **HTTP 431 Request Header Fields Too Large** error during login. Stirling PDF's default limit is `32768` (32 KB); raise it to resolve the error. + + + + ```yaml + server: + jetty: + max-http-request-header-size: 65536 # bytes (Stirling default: 32768) + ``` + + + ```yaml + environment: + SERVER_JETTY_MAX_HTTP_REQUEST_HEADER_SIZE: "65536" + ``` + + + ```bash + docker run -d \ + -p 8080:8080 \ + -e SERVER_JETTY_MAX_HTTP_REQUEST_HEADER_SIZE=65536 \ + stirlingtools/stirling-pdf:latest + ``` + + + +Raise the value further (for example `131072`) if the error persists, then restart Stirling PDF. + ## SSL/TLS Configuration Configure HTTPS for secure connections: diff --git a/docs/Configuration/OCR.md b/docs/Configuration/OCR.md index e441aa45..b26b360a 100644 --- a/docs/Configuration/OCR.md +++ b/docs/Configuration/OCR.md @@ -10,7 +10,11 @@ import TabItem from '@theme/TabItem'; This document provides instructions on how to add additional language packs for the OCR tab in Stirling PDF, both inside and outside of Docker. ## How does the OCR Work -Stirling PDF uses Tesseract for its text recognition. All credit goes to them for this awesome work! +Stirling PDF uses Tesseract for its text recognition. All credit goes to them for this awesome work! Note that OCR recognizes text only - it does not perform table-structure or formula recognition. + +:::note Requires a server backend +OCR runs on a server-side backend with Tesseract installed. The desktop app cannot OCR in local-only mode - connect it to Stirling Cloud or a self-hosted server that has OCR available. To OCR non-English documents, install the matching language pack as described below. +::: ## Language Packs diff --git a/docs/Configuration/UI Customisation.md b/docs/Configuration/UI Customisation.md index d2a7127b..0b07d93a 100644 --- a/docs/Configuration/UI Customisation.md +++ b/docs/Configuration/UI Customisation.md @@ -10,9 +10,7 @@ import TabItem from '@theme/TabItem'; Stirling PDF allows straightforward customization of the application name and appearance to make Stirling PDF your own. ## Application Name Settings -These settings control the visible application name: -- `appName` - The visible application name for your instance -- `homeDescription` - The description displayed on the homepage that first greets the user +This setting controls the application name: - `appNameNavbar` - Used as the browser tab title and as the issuer name shown in authenticator apps for two-factor (TOTP) login. Despite its name it is not shown in the navigation bar (which displays the logo), so do not leave it blank if you use TOTP. Empty falls back to "Stirling PDF". ## Show update notifications @@ -151,8 +149,6 @@ This approach requires maintaining your fork and manually merging updates. ```yaml ui: - appName: exampleAppName # Application's visible name - homeDescription: I am a description # Short description or tagline shown on homepage appNameNavbar: navbarName # Browser tab title and TOTP issuer label (not the navbar) system: @@ -166,25 +162,21 @@ This approach requires maintaining your fork and manually merging updates. **Option 1: Using Java Properties** ```bash java -jar Stirling-PDF.jar \ - -DAPP_HOME_NAME="New Application Name" \ + -DUI_APPNAMENAVBAR="Stirling PDF" \ -DSHOW_UPDATE=false \ -DSHOW_UPDATE_ONLY_ADMIN=false ``` **Option 2: Using Environment Variables** ```bash - export UI_APPNAME="Stirling PDF" - export UI_HOMEDESCRIPTION="Your locally hosted one-stop-shop for all your PDF needs." - export UI_APPNAVBARNAME="Stirling PDF" + export UI_APPNAMENAVBAR="Stirling PDF" export SYSTEM_SHOWUPDATE=false export SYSTEM_SHOWUPDATEONLYADMIN=false ``` ```bash - -e UI_APPNAME=Stirling PDF \ - -e UI_HOMEDESCRIPTION=Your locally hosted one-stop-shop for all your PDF needs. \ - -e UI_APPNAVBARNAME=Stirling PDF \ + -e UI_APPNAMENAVBAR=Stirling PDF \ -e SYSTEM_SHOWUPDATE=false \ -e SYSTEM_SHOWUPDATEONLYADMIN=false ``` @@ -192,9 +184,7 @@ This approach requires maintaining your fork and manually merging updates. ```yaml environment: - UI_APPNAME: Stirling PDF - UI_HOMEDESCRIPTION: Your locally hosted one-stop-shop for all your PDF needs. - UI_APPNAVBARNAME: Stirling PDF + UI_APPNAMENAVBAR: Stirling PDF SYSTEM_SHOWUPDATE: "false" SYSTEM_SHOWUPDATEONLYADMIN: "false" ``` diff --git a/docs/FAQ.md b/docs/FAQ.md index 18392038..97798b95 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -112,3 +112,29 @@ To disable authentication in the with-login version: For more details, see the [System and Security Configuration](./Configuration/System%20and%20Security.md#running-without-authentication) documentation. +### Q12: Where do my files go on the desktop app, and what does "uploading to server" mean? + +The desktop app runs a small Stirling PDF backend **inside the app on your own computer** (localhost). The Connection mode you pick (Settings -> Connection) decides where each tool runs: + +- **Local-only** (default; not signed in, no server connected): every tool runs on the local backend and your files never leave your device. If you use a tool the local backend can't perform (OCR, Office conversions, and similar), the file is **not** sent anywhere - the app stops and asks you to sign in to Stirling Cloud or connect to a self-hosted server. +- **Signed in to Stirling Cloud**: server-side tools are processed on Stirling's cloud (transient, not stored). +- **Connected to a self-hosted server**: server-side tools go only to your own server. + +Bottom line: in local-only mode a server-side tool is either run locally or blocked with a prompt - it is never silently uploaded anywhere. + +### Q13: Can I remove an existing watermark from a PDF? + +There is no dedicated watermark-removal tool. Stirling PDF can **add** watermarks (Add Watermark) but cannot automatically strip existing ones. + +### Q14: Can I add multi-line text or line breaks with Add Text, Stamp, or Watermark? + +Yes. Put a literal `\n` in the text field to force a line break; each line is rendered separately. + +### Q15: Why does my self-hosted instance make requests to js.stripe.com? + +Stripe's script loads only for the in-app purchase / billing UI. No PDF or document data is sent to Stripe. Fully offline/air-gapped instances are unaffected in normal use - the request only matters if you open the billing/upgrade screen. + +### Q16: Is a specific feature supported? + +We are continuously improving Stirling PDF, and the exact feature you're looking for might not be available yet - for example, a native Android app or in-app PDF translation. You can raise a feature request for any and all features on our [GitHub issues page](https://github.com/Stirling-Tools/Stirling-PDF/issues) with `[Feature Request]` in the title. + diff --git a/docs/Functionality/Content-Editing/Content-Editing.md b/docs/Functionality/Content-Editing/Content-Editing.md index af62e685..4a3e54f4 100644 --- a/docs/Functionality/Content-Editing/Content-Editing.md +++ b/docs/Functionality/Content-Editing/Content-Editing.md @@ -24,7 +24,7 @@ Tools for adding, extracting, and modifying content within PDF documents. ## Stamps & Annotations -- **Add Text**: Place custom text anywhere on your PDF. Pick the spot, then type a label, caption, or note directly onto the page. +- **Add Text**: Place custom text anywhere on your PDF. Pick the spot, then type a label, caption, or note directly onto the page. Multi-line text is supported: enter a literal `\n` in the text field to add a line break. - **Add Stamp**: Stamp your pages with your own text or an image. Set the position, size, rotation, and opacity, and apply it to one page or all of them. diff --git a/docs/Functionality/OCR.md b/docs/Functionality/OCR.md index 6415e76b..6443450e 100644 --- a/docs/Functionality/OCR.md +++ b/docs/Functionality/OCR.md @@ -9,6 +9,10 @@ description: Make scanned PDFs searchable and editable with OCR Make scanned PDFs searchable and selectable by recognizing text in images. Uses the Tesseract OCR engine. +:::note Requires a server backend +OCR needs a server-side backend with Tesseract installed. The desktop app cannot OCR in local-only mode - connect it to Stirling Cloud or a self-hosted server that has OCR available. +::: + --- ## When You Need OCR @@ -58,9 +62,11 @@ Available languages depend on which Tesseract language packs are installed. The ## Limitations +- Tesseract recognizes text only - it does not do table-structure or formula recognition - Handwritten text has limited accuracy - Stylized/decorative fonts and very small text (< 8pt) are challenging - For best results, use 300 DPI or higher scans with good contrast +- To OCR non-English documents, install the matching Tesseract language pack (see [Language Packs](#language-packs)) --- diff --git a/docs/Installation/Kubernetes.md b/docs/Installation/Kubernetes.md index a7e56659..e73dd066 100644 --- a/docs/Installation/Kubernetes.md +++ b/docs/Installation/Kubernetes.md @@ -18,6 +18,20 @@ Create a `values.yaml` file with the values you want to override from the [docum (For examples, see the comments in the default [values.yml](https://github.com/Stirling-Tools/Stirling-PDF-chart/blob/main/charts/stirling-pdf/values.yaml) file.) Then, add `-f values.yaml` to the `helm install` command. +### Persistent storage + +Stirling PDF keeps runtime data - user accounts, `settings.yml`, the internal database, and other state - under `/configs` (and related data paths). You can run without a persistent volume by supplying configuration through environment variables in your `values.yaml`, and the app works fine that way. + +A `PersistentVolumeClaim` is still recommended for reliable operation: it preserves data such as logins and settings across pod restarts and avoids errors from state being lost when a pod is rescheduled. The official Helm chart exposes persistence options in its [`values.yaml`](https://github.com/Stirling-Tools/Stirling-PDF-chart/blob/main/charts/stirling-pdf/values.yaml) - refer to the persistence-related keys there to enable a PVC and choose a storage class and size. + +### Overriding configuration + +Configuration is controlled through the same environment variables and `settings.yml` options used in other deployments, set through the chart's `values.yaml`. + +Create a `values.yaml` file and add the environment variables you want under the chart's env section, then pass it to Helm with `-f values.yaml`. See the comments in the default [`values.yaml`](https://github.com/Stirling-Tools/Stirling-PDF-chart/blob/main/charts/stirling-pdf/values.yaml) for the exact structure. + +For example, to raise the log level for debugging you can set the standard Stirling PDF logging environment variable (such as `LOGGING_LEVEL_STIRLING=DEBUG`) as an env entry in your `values.yaml`, alongside any other environment variables like locale, security, or OAuth/SAML settings. + ### Upgrade the helm chart ```bash diff --git a/docs/Installation/Versions.md b/docs/Installation/Versions.md index 1b08ce04..df0f2669 100644 --- a/docs/Installation/Versions.md +++ b/docs/Installation/Versions.md @@ -36,6 +36,8 @@ Additional features become available automatically when you install: ## Feature Comparison +For the desktop app, the **Ultra-Lite** column below lists the tools that run locally and fully offline on the bundled backend. The **Full-only** tools (OCR, Office conversions, and other tools that depend on external binaries) require a connected server - either Stirling Cloud or your own self-hosted server. + Here are the different technologies each version uses: | Technology | Ultra-Lite | Full | diff --git a/docs/Installation/Windows.md b/docs/Installation/Windows.md index 19070097..ebd09d26 100644 --- a/docs/Installation/Windows.md +++ b/docs/Installation/Windows.md @@ -119,6 +119,11 @@ When the mode is set by an administrator through a provisioning file (see [Manag For silent or headless installs and pre-configuring the app for managed fleets - server URL, connection lock, and update mode via MSI or `winget` parameters, or a provisioning file - see [Managed Desktop Deployment](./Managed%20Deployment.md). +### Desktop app troubleshooting + +- **App shows in Task Manager but no window appears** - The desktop app renders its UI using the Microsoft Edge WebView2 Runtime. If the process is running but nothing is displayed, install the [Microsoft Edge WebView2 Runtime](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) and launch the app again. +- **Connecting to a self-hosted server** - Use your backend server URL (for example `http://192.168.1.53:8080`). To verify the server is reachable, open `http://:/api/v1/info/status` in a browser - it should return JSON with a status of `UP`. + ## Server Version (For Hosting and Sharing) Want to host Stirling PDF on a Windows server for multiple users? Use the server version. @@ -169,6 +174,7 @@ Python and its related tools enable various features in Stirling PDF: 1. Python Installation: - Download Python from [Python's official site](https://www.python.org/downloads/) + - **Recommended version:** install **Python 3.11.x**. Python 3.12 and newer can break the unoserver/unoconv LibreOffice conversion path, so 3.11 is the safe choice. - During installation, **IMPORTANT**: Check "Add Python to PATH" - Verify installation by opening Command Prompt and running: ```bash