Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/Advanced Configuration/External Database.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ PostgreSQL is currently the only supported variant, others will be added on requ
You can configure the new `Datasource` property in your `settings.yml` to connect to your external database:

> #### ⚠️ Note
> _To use the external database feature, you will need to have a valid enterprise license and set the environment variable `DISABLE_ADDITIONAL_FEATURES` to `false`._
> _To use the external database feature, you will need to have a valid enterprise license and set the environment variable `DOCKER_ENABLE_SECURITY` to `true`._

<Tabs groupId="external-db-config">
<TabItem value="settings" label="Settings File">
Expand Down Expand Up @@ -78,7 +78,7 @@ services:
depends_on:
- db
environment:
DISABLE_ADDITIONAL_FEATURES: "false" "true"
DOCKER_ENABLE_SECURITY: "true"
SYSTEM_DATASOURCE_ENABLECUSTOMDATABASE: "true"
SYSTEM_DATASOURCE_CUSTOMDATABASEURL: "jdbc:postgresql://db:5432/stirling_pdf"
SYSTEM_DATASOURCE_USERNAME: "admin"
Expand All @@ -87,7 +87,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
- `DOCKER_ENABLE_SECURITY`: Set this to `true` 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_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
Expand All @@ -101,7 +101,7 @@ services:
depends_on:
- db
environment:
DISABLE_ADDITIONAL_FEATURES: "false" "true"
DOCKER_ENABLE_SECURITY: "true"
SYSTEM_DATASOURCE_ENABLECUSTOMDATABASE: "true"
SYSTEM_DATASOURCE_CUSTOMDATABASEURL: "jdbc:postgresql://db:5432/stirling_pdf"
SYSTEM_DATASOURCE_USERNAME: "admin"
Expand Down
2 changes: 1 addition & 1 deletion docs/Advanced Configuration/How to add configurations.md
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@ There is an additional config file ``/configs/custom_settings.yml`` where users

- ``SYSTEM_ROOTURIPATH`` ie set to ``/pdf-app`` to Set the application's root URI to ``localhost:8080/pdf-app``
- ``SYSTEM_CONNECTIONTIMEOUTMINUTES`` to set custom connection timeout values
- ``DISABLE_ADDITIONAL_FEATURES`` to tell docker to download security jar (required as false for auth login)
- ``DOCKER_ENABLE_SECURITY`` to tell docker to download security jar (required as true for auth login)
- ``LANGS`` to define custom font libraries to install for use for document conversions

### Local
Expand Down
14 changes: 7 additions & 7 deletions docs/Advanced Configuration/Single Sign-On Configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,9 +151,9 @@ Assertion Consumer Service (ACS) URL The default is `stirling`
- `security.saml2.idpSingleLoginUrl`: The URL given by your Provider to initiate the SSO flow
- `security.saml2.idpSingleLogoutUrl`: The URL given by your Provider to initiate the SLO flow
- `security.saml2.idpIssuer`: The name of your Provider
- `security.saml2.idpCert`: The signing certificate given by your Provider in `.pem` format. Place in `stirling-pdf/src/main/resources`
- `security.saml2.privateKey`: Your private key from your keypair in `.key` format. Place in `stirling-pdf/src/main/resources`
- `security.saml2.spCert`: classpath:certificate.crt from your keypair in `.crt` format. Place in `stirling-pdf/src/main/resources`
- `security.saml2.idpCert`: The signing certificate given by your Provider in `.pem` format. Place in `src/main/resources`
- `security.saml2.privateKey`: Your private key from your keypair in `.key` format. Place in `src/main/resources`
- `security.saml2.spCert`: classpath:certificate.crt from your keypair in `.crt` format. Place in `src/main/resources`

### Generating a Keypair

Expand All @@ -174,7 +174,7 @@ A self-signed certificate is not verified by a Certificate Authority (CA), which
- `out certificate.crt`: Specifies the output file where the self-signed certificate will be saved

After generating the keypair, the `.key` and `.crt` files should be located in the directory you executed the above command in.
Move the files to `stirling-pdf/src/main/resources`.
Move the files to `src/main/resources`.

Once you have added your configuration, you should see the button for your chosen Provider on the login page prompting you to log in:

Expand Down Expand Up @@ -222,7 +222,7 @@ Below are examples of the full configuration for both OAuth 2 and SAML 2:
</TabItem>
<TabItem value="local" label="Local Environment">
```bash
export DISABLE_ADDITIONAL_FEATURES=false
export DOCKER_ENABLE_SECURITY=true
export SECURITY_ENABLELOGIN=true
export SECURITY_OAUTH2_ENABLED=true
export SECURITY_OAUTH2_AUTOCREATEUSER=false
Expand All @@ -249,7 +249,7 @@ Below are examples of the full configuration for both OAuth 2 and SAML 2:
</TabItem>
<TabItem value="docker-run" label="Docker Run">
```bash
-e DISABLE_ADDITIONAL_FEATURES=false \
-e DOCKER_ENABLE_SECURITY=true \
-e SECURITY_ENABLELOGIN=true \
-e SECURITY_OAUTH2_ENABLED=true \
-e SECURITY_OAUTH2_AUTOCREATEUSER=false \
Expand All @@ -276,7 +276,7 @@ Below are examples of the full configuration for both OAuth 2 and SAML 2:
<TabItem value="docker-compose" label="Docker Compose">
```yaml
environment:
DISABLE_ADDITIONAL_FEATURES=false
DOCKER_ENABLE_SECURITY=true
SECURITY_ENABLELOGIN=true
SECURITY_OAUTH2_ENABLED=true
SECURITY_OAUTH2_AUTOCREATEUSER=false
Expand Down
12 changes: 6 additions & 6 deletions docs/Advanced Configuration/System and Security.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ import TabItem from '@theme/TabItem';

# Login, System and Security

Stirling PDF allows customization of system and security settings. For security features to be enabled, you must use the security jar. For Docker users, this means setting `DISABLE_ADDITIONAL_FEATURES` to `false` via an environment variable.
Stirling PDF allows customization of system and security settings. For security features to be enabled, you must use the security jar. For Docker users, this means setting `DOCKER_ENABLE_SECURITY` to `true` via an environment variable.

## Basic Security Settings

Expand All @@ -19,7 +19,7 @@ Stirling PDF allows customization of system and security settings. For security

### Prerequisites
1. Ensure the `/configs` directory is mounted as a volume in Docker for persistence across updates
2. For Docker users: Set `DISABLE_ADDITIONAL_FEATURES=false` in environment variables
2. For Docker users: Set `DOCKER_ENABLE_SECURITY=true` in environment variables
3. Enable login either via `settings.yml` or set `SECURITY_ENABLELOGIN=true`

### Initial Login Credentials
Expand Down Expand Up @@ -76,25 +76,25 @@ When using the API:

**Option 1: Using Java Properties**
```bash
java -jar Stirling-PDF.jar -DDISABLE_ADDITIONAL_FEATURES=false -DSECURITY_ENABLELOGIN=true
java -jar Stirling-PDF.jar -DDOCKER_ENABLE_SECURITY=true -DSECURITY_ENABLELOGIN=true
```

**Option 2: Using Environment Variables**
```bash
export DISABLE_ADDITIONAL_FEATURES=false
export DOCKER_ENABLE_SECURITY=true
export SECURITY_ENABLELOGIN=true
```
</TabItem>
<TabItem value="docker-run" label="Docker Run">
```bash
-e DISABLE_ADDITIONAL_FEATURES=false \
-e DOCKER_ENABLE_SECURITY=true \
-e SECURITY_ENABLELOGIN=true \
```
</TabItem>
<TabItem value="docker-compose" label="Docker Compose">
```yaml
environment:
DISABLE_ADDITIONAL_FEATURES: false true
DOCKER_ENABLE_SECURITY: true
SECURITY_ENABLELOGIN: true
```
</TabItem>
Expand Down
12 changes: 6 additions & 6 deletions docs/Advanced Configuration/UI Customisation.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,29 +50,29 @@ To override a file:
3. Create the same file path under your `customFiles` directory following the same directory structure
4. Paste and modify the contents as needed

Note: When overriding templates, first copy the existing template from the [source repository](https://github.com/Stirling-Tools/Stirling-PDF/tree/main/stirling-pdf/src/main/resources/templates) to maintain the base structure.
Note: When overriding templates, first copy the existing template from the [source repository](https://github.com/Stirling-Tools/Stirling-PDF/tree/main/src/main/resources/templates) to maintain the base structure.

1. To replace the favicon:
```
customFiles/static/favicon.svg
```
Original file: [stirling-pdf/src/main/resources/static/favicon.svg](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/stirling-pdf/src/main/resources/static/favicon.svg)
Original file: [src/main/resources/static/favicon.svg](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/src/main/resources/static/favicon.svg)

2. To override a Bootstrap icon font:
```
customFiles/static/css/fonts/bootstrap-icons.woff
```
Original file: [stirling-pdf/src/main/resources/static/css/fonts/bootstrap-icons.woff](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/stirling-pdf/src/main/resources/static/css/fonts/bootstrap-icons.woff)
Original file: [src/main/resources/static/css/fonts/bootstrap-icons.woff](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/src/main/resources/static/css/fonts/bootstrap-icons.woff)

3. To modify a template:
```
customFiles/templates/fragments/common.html
```
Original file: [stirling-pdf/src/main/resources/templates/fragments/common.html](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/stirling-pdf/src/main/resources/templates/fragments/common.html)
Original file: [src/main/resources/templates/fragments/common.html](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/src/main/resources/templates/fragments/common.html)

The original files can be found in the GitHub repository under:
- Static files: [stirling-pdf/src/main/resources/static/](https://github.com/Stirling-Tools/Stirling-PDF/tree/main/stirling-pdf/src/main/resources/static)
- Templates (HTML files): [stirling-pdf/src/main/resources/templates/](https://github.com/Stirling-Tools/Stirling-PDF/tree/main/stirling-pdf/src/main/resources/templates)
- Static files: [src/main/resources/static/](https://github.com/Stirling-Tools/Stirling-PDF/tree/main/src/main/resources/static)
- Templates (HTML files): [src/main/resources/templates/](https://github.com/Stirling-Tools/Stirling-PDF/tree/main/src/main/resources/templates)



Expand Down
4 changes: 2 additions & 2 deletions docs/Installation/Docker Install.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ docker run -d \
-v "./StirlingPDF/customFiles:/customFiles/" \
-v "./StirlingPDF/logs:/logs/" \
-v "./StirlingPDF/pipeline:/pipeline/" \
-e DISABLE_ADDITIONAL_FEATURES=true \
-e DOCKER_ENABLE_SECURITY=false \
-e LANGS=en_GB \
docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
```
Expand All @@ -49,7 +49,7 @@ services:
- ./StirlingPDF/logs:/logs/
- ./StirlingPDF/pipeline:/pipeline/
environment:
- DISABLE_ADDITIONAL_FEATURES=false
- DOCKER_ENABLE_SECURITY=false
- LANGS=en_GB
```

Expand Down
74 changes: 15 additions & 59 deletions docs/Installation/Unix.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@ sidebar_position: 2
id: Unix Installation
title: Unix Installation Guide
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Expand Down Expand Up @@ -67,19 +66,7 @@ Install the following software, if not already installed:
### Step 2: Clone and Build jbig2enc (Only required for certain OCR functionality)

<Tabs groupId="unix-systems">
<TabItem value="debian" label="Debian">
```bash
mkdir ~/.git
cd ~/.git &&\
git clone https://github.com/agl/jbig2enc.git &&\
cd jbig2enc &&\
./autogen.sh &&\
./configure &&\
make &&\
sudo make install
```
</TabItem>
<TabItem value="fedora" label="Fedora">
<TabItem value="debian-fedora" label="Debian/Fedora">
```bash
mkdir ~/.git
cd ~/.git &&\
Expand All @@ -103,7 +90,6 @@ Install the following software, if not already installed:
Next we need to install LibreOffice for conversions, tesseract for OCR, and opencv for pattern recognition functionality.

Install the following software:

- libreoffice (libreoffice-core libreoffice-common libreoffice-writer libreoffice-calc libreoffice-impress)
- python3-uno
- unoserver
Expand Down Expand Up @@ -133,33 +119,23 @@ Install the following software:
</Tabs>

### Step 4: Grab latest Stirling-PDF Jar

The JAR can be downloaded in two versions, [normal](https://files.stirlingpdf.com/Stirling-PDF.jar) and [security](https://files.stirlingpdf.com/Stirling-PDF-with-login.jar)
The JAR can be downloaded in two versions, [normal](https://files.stirlingpdf.com/Stirling-PDF.jar) and [security](https://files.stirlingpdf.com/Stirling-PDF-with-login.jar)

### Step 5: Move jar to desired location

You can move this file to a desired location, for example, `/opt/Stirling-PDF/`.
You must also move the Script folder within the Stirling-PDF repo that you have downloaded to this directory.
This folder is required for the python scripts using OpenCV.

<Tabs groupId="user-type">
<TabItem value="debian" label="Debian (Root)">
```bash
sudo mkdir /opt/Stirling-PDF &&\
sudo mv ./build/libs/Stirling-PDF-*.jar /opt/Stirling-PDF/ &&\
sudo mv scripts /opt/Stirling-PDF/ &&\
echo "Scripts installed."
```
</TabItem>
<TabItem value="fedora" label="Fedora (Root)">
<TabItem value="root" label="Root User">
```bash
sudo mkdir /opt/Stirling-PDF &&\
sudo mv ./build/libs/Stirling-PDF-*.jar /opt/Stirling-PDF/ &&\
sudo mv scripts /opt/Stirling-PDF/ &&\
echo "Scripts installed."
```
</TabItem>
<TabItem value="nix" label="Nix (Non-root)">
<TabItem value="non-root" label="Non-root User">
```bash
mv ./build/libs/Stirling-PDF-*.jar ./Stirling-PDF-*.jar
```
Expand All @@ -176,7 +152,7 @@ If you plan to use the OCR (Optical Character Recognition) functionality, you mi
sudo apt update &&\
# All languages
# sudo apt install -y 'tesseract-ocr-*'

# Find languages:
apt search tesseract-ocr-

Expand All @@ -188,7 +164,7 @@ If you plan to use the OCR (Optical Character Recognition) functionality, you mi
```bash
# All languages
# sudo dnf install -y tesseract-langpack-*

# Find languages:
dnf search -C tesseract-langpack-

Expand All @@ -208,41 +184,28 @@ If you plan to use the OCR (Optical Character Recognition) functionality, you mi
3. Please view [tesseract install guide](https://tesseract.readthedocs.io/en/latest/installation.html) for more info.

**IMPORTANT:** DO NOT REMOVE EXISTING `eng.traineddata`, IT'S REQUIRED.

</TabItem>
</Tabs>

### Step 7: Run Stirling-PDF

<Tabs groupId="unix-systems">
<TabItem value="debian" label="Debian-based Systems">
```bash
java -jar /opt/Stirling-PDF/Stirling-PDF-*.jar
```
</TabItem>
<TabItem value="fedora" label="Fedora-based Systems">
```bash
java -jar /opt/Stirling-PDF/Stirling-PDF-*.jar

Since libreoffice, soffice, and conversion tools have their dbus_tmp_dir set as `dbus_tmp_dir="/run/user/$(id -u)/libreoffice-dbus"`, you might get the following error:
```
</TabItem>
<TabItem value="nix" label="Nix Package Manager">
```bash
java -jar /opt/Stirling-PDF/Stirling-PDF-*.jar
[Thread-7] INFO s.s.SPDF.utils.ProcessExecutor - mkdir: cannot create directory '/run/user/1501': Permission denied
```
Since libreoffice, soffice, and conversion tools have their dbus_tmp_dir set as `dbus_tmp_dir="/run/user/$(id -u)/libreoffice-dbus"`, you get the following error:
`[Thread-7] INFO s.s.SPDF.utils.ProcessExecutor - mkdir: cannot create directory '/run/user/1501': Permission denied`
To resolve this, use:
`bash
mkdir temp
export DBUS_SESSION_BUS_ADDRESS="unix:path=./temp"
`
</TabItem>
</Tabs>
To resolve this, use:
```bash
mkdir temp
export DBUS_SESSION_BUS_ADDRESS="unix:path=./temp"
```

### Step 8: Adding a Desktop Icon

This will add a modified Appstarter to your Appmenu.

```bash
location=$(pwd)/gradlew
image=$(pwd)/docs/stirling-transparent.svg
Expand Down Expand Up @@ -285,21 +248,17 @@ SERVER_PORT="3000"
### Optional: Run Stirling-PDF as a service (requires root).

First create a .env file, where you can store environment variables:

```
touch /opt/Stirling-PDF/.env
```

In this file you can add all variables, one variable per line, as stated in the main readme (for example SYSTEM_DEFAULTLOCALE="de-DE").

Create a new file where we store our service settings and open it with nano editor:

```
nano /etc/systemd/system/stirlingpdf.service
```

Paste this content, make sure to update the filename of the jar-file. Press Ctrl+S and Ctrl+X to save and exit the nano editor:

```
[Unit]
Description=Stirling-PDF service
Expand Down Expand Up @@ -329,19 +288,16 @@ sudo systemctl daemon-reload
```

Enable the service to tell the service to start it automatically:

```
sudo systemctl enable stirlingpdf.service
```

See the status of the service:

```
sudo systemctl status stirlingpdf.service
```

Manually start/stop/restart the service:

```
sudo systemctl start stirlingpdf.service
sudo systemctl stop stirlingpdf.service
Expand Down Expand Up @@ -371,4 +327,4 @@ system:
operations:
weasyprint: "" #Defaults to /opt/venv/bin/weasyprint
unoconvert: "" #Defaults to /opt/venv/bin/unoconvert
```
```
Loading