diff --git a/docs/Advanced Configuration/DATABASE.md b/docs/Advanced Configuration/DATABASE.md index 73fb6db..8e5098c 100644 --- a/docs/Advanced Configuration/DATABASE.md +++ b/docs/Advanced Configuration/DATABASE.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 9 +--- + # Database Backups ## Functionality Overview diff --git a/docs/Advanced Configuration/Endpoint or Feature Customisation.md b/docs/Advanced Configuration/Endpoint or Feature Customisation.md index 3a43bbd..c410d16 100644 --- a/docs/Advanced Configuration/Endpoint or Feature Customisation.md +++ b/docs/Advanced Configuration/Endpoint or Feature Customisation.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 5 --- # Endpoints Customisation @@ -10,7 +10,7 @@ There are many use-cases for this such as - Cleanup interface for features you don't use -To do this `ENDPOINTS_TO_REMOVE` and `GROUPS_TO_REMOVE` have been setup. +To do this `ENDPOINTS_TO_REMOVE` and `GROUPS_TO_REMOVE` have been set up. They can include comma-separated lists of endpoints and groups to disable. For example, `ENDPOINTS_TO_REMOVE=img-to-pdf,remove-pages` would disable both the "image to PDF" and "remove pages" functionalities. `GROUPS_TO_REMOVE=Libre` Would disable a group of endpoints, in this case all endpoints which use Libre in the backend. diff --git a/docs/Advanced Configuration/External Database.md b/docs/Advanced Configuration/External Database.md new file mode 100644 index 0000000..c062240 --- /dev/null +++ b/docs/Advanced Configuration/External Database.md @@ -0,0 +1,123 @@ +--- +sidebar_position: 8 +id: External Database +title: External Database +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + +# Using an External Database + +It is possible to use your own external database with Stirling PDF rather than the default H2 database if you wish. +PostgreSQL is currently the only supported variant, others will be added on request. + +### Setting Up External Database Configuration +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 `DOCKER_ENABLE_SECURITY` to `true`._ + + + + +```yaml + datasource: + enableCustomDatabase: false + customDatabaseUrl: jdbc:postgresql://localhost:5432/postgres + username: postgres + password: postgres + type: postgresql + hostName: localhost + port: 5432 + name: postgres +``` + +- `enableCustomDatabase`: Set this property to `true` to enable use of the custom database **Note: An enterprise license to use this feature** +- `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 + +If you would like more fine-grained control of the database connection, you can also use the following properties: + +#### Fine-grained Database Configuration +- `type`: The database type. Available options are `h2` and `postgresql` +- `hostName`: The host name of the database connection url (e.g. 'localhost') +- `port`: The port number of the database connection url (e.g. 8080) +- `name`: The name of the custom database. This should match the name you have set for your database + + + + +```yaml +services: + db: + image: 'postgres:17.2-alpine' + container_name: db + ports: + - "5432:5432" + environment: + POSTGRES_DB: "stirling_pdf" + POSTGRES_USER: "admin" + POSTGRES_PASSWORD: "stirling" +``` + +- `container_name`: This is the name of your database container. This should match the name of the container under `services` as this is what Docker will use to refer to your database +- `ports`: Specify the port number for your database. The number on the left is the port number the container will access the database internally. The number on the right is the port number the Stirling PDF app will use to connect to the database externally. Ensure this matches the port number in the connection url for your database otherwise the app will not be able to access it. +- `POSTGRES_DB`: An environment variable for the database container. Specify the name of the custom database here +- `POSTGRES_USER`: An environment variable for the database container. Specify the username for the database +- `POSTGRES_PASSWORD`: An environment variable for the database container. Specify the password for the database + +You will also need to update the Docker configuration in your app in order to connect to the database: + +```yaml +services: + stirling-pdf: + depends_on: + - db + environment: + DOCKER_ENABLE_SECURITY: "true" + SYSTEM_DATASOURCE_ENABLECUSTOMDATABASE: "true" + SYSTEM_DATASOURCE_CUSTOMDATABASEURL: "jdbc:postgresql://db:5432/stirling_pdf" + SYSTEM_DATASOURCE_USERNAME: "admin" + SYSTEM_DATASOURCE_PASSWORD: "stirling" + # further configuration +``` + +- `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 +- `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_DATASOURCETYPE`, `SYSTEM_DATASOURCEHOSTNAME`, `SYSTEM_DATASOURCEPORT`, `SYSTEM_DATASOURCENAME`), 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 + +Below is an example of what your configuration should look like after configuring the custom database: + +```yaml +services: + stirling-pdf: + depends_on: + - db + environment: + DOCKER_ENABLE_SECURITY: "true" + SYSTEM_DATASOURCE_ENABLECUSTOMDATABASE: "true" + SYSTEM_DATASOURCE_CUSTOMDATABASEURL: "jdbc:postgresql://db:5432/stirling_pdf" + SYSTEM_DATASOURCE_USERNAME: "admin" + SYSTEM_DATASOURCE_PASSWORD: "stirling" + # further configuration + + db: + image: 'postgres:17.2-alpine' + container_name: db + ports: + - "5432:5432" + environment: + POSTGRES_DB: "stirling_pdf" + POSTGRES_USER: "admin" + POSTGRES_PASSWORD: "stirling" +``` + + + + +*Example configuration can be found in [exampleYmlFiles/docker-compose-latest-fat-security-postgres.yml](https://github.com/Stirling-Tools/Stirling-PDF/blob/428b4238e3a7280d71697d994a66174a250387a7/exampleYmlFiles/docker-compose-latest-fat-security-postgres.yml)* \ No newline at end of file diff --git a/docs/Advanced Configuration/FolderScanning.md b/docs/Advanced Configuration/FolderScanning.md index 5e78e12..61a3aee 100644 --- a/docs/Advanced Configuration/FolderScanning.md +++ b/docs/Advanced Configuration/FolderScanning.md @@ -1,12 +1,12 @@ --- -sidebar_position: 4 +sidebar_position: 7 id: Folder Scanning title: Folder Scanning --- ## User Guide for Local Directory Scanning and File Processing -Folder scanning uses settings configured from our pipeline tool, it is adviced you first read the [Pipeline Guide](/Advanced%20Configuration/Pipeline) +Folder scanning uses settings configured from our pipeline tool, it is advised you first read the [Pipeline Guide](/Advanced%20Configuration/Pipeline) ### Setting Up Watched Folders - Create a folder where you want your files to be monitored. This is your 'watched folder'. diff --git a/docs/Advanced Configuration/OCR.md b/docs/Advanced Configuration/OCR.md index 51fad87..ec597a6 100644 --- a/docs/Advanced Configuration/OCR.md +++ b/docs/Advanced Configuration/OCR.md @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 6 id: OCR title: OCR (Optical Character Recognition) --- @@ -21,7 +21,7 @@ Tesseract OCR supports a variety of languages. You can find additional language Depending on your requirements, you can choose the appropriate language pack for your use case. By default, Stirling-PDF uses `tessdata_fast` for English, but this can be replaced. -### Installing Language Packs mannually +### Installing Language Packs manually 1. Download the desired language pack(s) by selecting the `.traineddata` file(s) for the language(s) you need. 2. Place the `.traineddata` files in the Tesseract tessdata directory: `/usr/share/tessdata` (or equivalent) diff --git a/docs/Advanced Configuration/Other Customisations.md b/docs/Advanced Configuration/Other Customisations.md index 1c28e39..97d524d 100644 --- a/docs/Advanced Configuration/Other Customisations.md +++ b/docs/Advanced Configuration/Other Customisations.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 12 --- # Other Customisations @@ -8,7 +8,7 @@ Stirling PDF offers various other customisation options, such as: ### Defaulting Language Default language selection via the `APP_LOCALE` environment variable. Accepted values include `de-DE`, `fr-FR`, `ar-AR` and all other languages codes that are within Stirling-PDFs current list. -### Google Search Visability (robots.txt) +### Google Search Visibility (robots.txt) Enable or disable search engine visibility with the `ALLOW_GOOGLE_VISIBILITY` variable. ### Custom Root path diff --git a/docs/Advanced Configuration/Pipeline.md b/docs/Advanced Configuration/Pipeline.md index 5e45d2d..b735605 100644 --- a/docs/Advanced Configuration/Pipeline.md +++ b/docs/Advanced Configuration/Pipeline.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 10 id: Pipeline title: Pipeline Automation --- diff --git a/docs/Advanced Configuration/Sign with custom files.md b/docs/Advanced Configuration/Sign with custom files.md index 1221e2e..b8e9fd4 100644 --- a/docs/Advanced Configuration/Sign with custom files.md +++ b/docs/Advanced Configuration/Sign with custom files.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 11 --- # Visual Sign with Custom File Storage diff --git a/docs/Advanced Configuration/Single Sign-On Configuration.md b/docs/Advanced Configuration/Single Sign-On Configuration.md index 657a6de..047f5e9 100644 --- a/docs/Advanced Configuration/Single Sign-On Configuration.md +++ b/docs/Advanced Configuration/Single Sign-On Configuration.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 3 +--- + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; diff --git a/docs/Advanced Configuration/System and Security.md b/docs/Advanced Configuration/System and Security.md index d080198..16648e3 100644 --- a/docs/Advanced Configuration/System and Security.md +++ b/docs/Advanced Configuration/System and Security.md @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 2 --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; diff --git a/docs/Advanced Configuration/UI Customisation.md b/docs/Advanced Configuration/UI Customisation.md index 27ce91d..59d127d 100644 --- a/docs/Advanced Configuration/UI Customisation.md +++ b/docs/Advanced Configuration/UI Customisation.md @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 4 --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';