DGNum/Stirling-PDF
15
0
Fork 0
Code Issues 4 Pull requests 1 Projects Releases Packages Wiki Activity

adding documentation for database import and export (#1528)

Browse source 
* adding documentation for database import and export

* Update DATABASE.md
This commit is contained in:
Ludy 2024-07-06 14:24:32 +02:00 committed by GitHub
parent 31ce5b1221
commit 4088208fc8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 75 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

40
DATABASE.md Normal file
View file

@ -0,0 +1,40 @@
# New Database Backup and Import Functionality
**Full activation will take place on approximately January 5th, 2025!**
Why is the waiting time six months?
There are users who only install updates sporadically; if they skip the preparation, it can/will lead to data loss in the database.
## Functionality Overview
The newly introduced feature enhances the application with robust database backup and import capabilities. This feature is designed to ensure data integrity and provide a straightforward way to manage database backups. Here's how it works:
1. Automatic Backup Creation
- The system automatically creates a database backup every day at midnight. This ensures that there is always a recent backup available, minimizing the risk of data loss.
2. Manual Backup Export
- Admin actions that modify the user database trigger a manual export of the database. This keeps the backup up-to-date with the latest changes and provides an extra layer of data security.
3. Importing Database Backups
- Admin users can import a database backup either via the web interface or API endpoints. This allows for easy restoration of the database to a previous state in case of data corruption or other issues.
- The import process ensures that the database structure and data are correctly restored, maintaining the integrity of the application.
4. Managing Backup Files
- Admins can view a list of all existing backup files, along with their creation dates and sizes. This helps in managing storage and identifying the most recent or relevant backups.
- Backup files can be downloaded for offline storage or transferred to other environments, providing flexibility in database management.
- Unnecessary backup files can be deleted through the interface to free up storage space and maintain an organized backup directory.
## User Interface
### Web Interface
1. Upload SQL files to import database backups.
2. View details of existing backups, such as file names, creation dates, and sizes.
3. Download backup files for offline storage.
4. Delete outdated or unnecessary backup files.
### API Endpoints
1. Import database backups by uploading SQL files.
2. Download backup files.
3. Delete backup files.
This new functionality streamlines database management, ensuring that backups are always available and easy to manage, thus improving the reliability and resilience of the application.

68
README.md
View file

@ -26,6 +26,7 @@ All files and PDFs exist either exclusively on the client side, reside in server
- Parallel file processing and downloads - Parallel file processing and downloads
- API for integration with external scripts - API for integration with external scripts
- Optional Login and Authentication support (see [here](https://github.com/Stirling-Tools/Stirling-PDF/tree/main#login-authentication) for documentation) - Optional Login and Authentication support (see [here](https://github.com/Stirling-Tools/Stirling-PDF/tree/main#login-authentication) for documentation)
- Database Backup and Import (see [here](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DATABASE.md) for documentation)
## **PDF Features** ## **PDF Features**
@ -234,35 +235,36 @@ security:
csrfDisabled: true # Set to 'true' to disable CSRF protection (not recommended for production) csrfDisabled: true # Set to 'true' to disable CSRF protection (not recommended for production)
loginAttemptCount: 5 # lock user account after 5 tries loginAttemptCount: 5 # lock user account after 5 tries
loginResetTimeMinutes: 120 # lock account for 2 hours after x attempts loginResetTimeMinutes: 120 # lock account for 2 hours after x attempts
# initialLogin: loginMethod: all # 'all' (Login Username/Password and OAuth2[must be enabled and configured]), 'normal'(only Login with Username/Password) or 'oauth2'(only Login with OAuth2)
# username: "admin" # Initial username for the first login initialLogin:
# password: "stirling" # Initial password for the first login username: '' # Initial username for the first login
# oauth2: password: '' # Initial password for the first login
# enabled: false # set to 'true' to enable login (Note: enableLogin must also be 'true' for this to work) oauth2:
# issuer: "" # set to any provider that supports OpenID Connect Discovery (/.well-known/openid-configuration) end-point enabled: false # set to 'true' to enable login (Note: enableLogin must also be 'true' for this to work)
# clientId: "" # Client ID from your provider client:
# clientSecret: "" # Client Secret from your provider keycloak:
# autoCreateUser: false # set to 'true' to allow auto-creation of non-existing users issuer: '' # URL of the Keycloak realm's OpenID Connect Discovery endpoint
# useAsUsername: "email" # Default is 'email'; custom fields can be used as the username clientId: '' # Client ID for Keycloak OAuth2
# scopes: "openid, profile, email" # Specify the scopes for which the application will request permissions clientSecret: '' # Client Secret for Keycloak OAuth2
# provider: "google" # Set this to your OAuth provider's name, e.g., 'google' or 'keycloak' scopes: openid, profile, email # Scopes for Keycloak OAuth2
# client: useAsUsername: preferred_username # Field to use as the username for Keycloak OAuth2
# google: google:
# clientId: "" # Client ID for Google OAuth2 clientId: '' # Client ID for Google OAuth2
# clientSecret: "" # Client Secret for Google OAuth2 clientSecret: '' # Client Secret for Google OAuth2
# scopes: "https://www.googleapis.com/auth/userinfo.email, https://www.googleapis.com/auth/userinfo.profile" # Scopes for Google OAuth2 scopes: https://www.googleapis.com/auth/userinfo.email, https://www.googleapis.com/auth/userinfo.profile # Scopes for Google OAuth2
# useAsUsername: "email" # Field to use as the username for Google OAuth2 useAsUsername: email # Field to use as the username for Google OAuth2
# github: github:
# clientId: "" # Client ID for GitHub OAuth2 clientId: '' # Client ID for GitHub OAuth2
# clientSecret: "" # Client Secret for GitHub OAuth2 clientSecret: '' # Client Secret for GitHub OAuth2
# scopes: "read:user" # Scope for GitHub OAuth2 scopes: read:user # Scope for GitHub OAuth2
# useAsUsername: "login" # Field to use as the username for GitHub OAuth2 useAsUsername: login # Field to use as the username for GitHub OAuth2
# keycloak: issuer: '' # set to any provider that supports OpenID Connect Discovery (/.well-known/openid-configuration) end-point
# issuer: "http://192.168.0.123:8888/realms/stirling-pdf" # URL of the Keycloak realm's OpenID Connect Discovery endpoint clientId: '' # Client ID from your provider
# clientId: "stirling-pdf" # Client ID for Keycloak OAuth2 clientSecret: '' # Client Secret from your provider
# clientSecret: "" # Client Secret for Keycloak OAuth2 autoCreateUser: false # set to 'true' to allow auto-creation of non-existing users
# scopes: "openid, profile, email" # Scopes for Keycloak OAuth2 useAsUsername: email # Default is 'email'; custom fields can be used as the username
# useAsUsername: "email" # Field to use as the username for Keycloak OAuth2 scopes: openid, profile, email # Specify the scopes for which the application will request permissions
provider: google # Set this to your OAuth provider's name, e.g., 'google' or 'keycloak'
system: system:
defaultLocale: 'en-US' # Set the default language (e.g. 'de-DE', 'fr-FR', etc) defaultLocale: 'en-US' # Set the default language (e.g. 'de-DE', 'fr-FR', etc)
@ -273,9 +275,9 @@ system:
customHTMLFiles: false # enable to have files placed in /customFiles/templates override the existing template html files customHTMLFiles: false # enable to have files placed in /customFiles/templates override the existing template html files
ui: ui:
appName: null # Application's visible name appName: '' # Application's visible name
homeDescription: null # Short description or tagline shown on homepage. homeDescription: '' # Short description or tagline shown on homepage.
appNameNavbar: null # Name displayed on the navigation bar appNameNavbar: '' # Name displayed on the navigation bar
endpoints: endpoints:
toRemove: [] # List endpoints to disable (e.g. ['img-to-pdf', 'remove-pages']) toRemove: [] # List endpoints to disable (e.g. ['img-to-pdf', 'remove-pages'])
@ -309,7 +311,7 @@ For those wanting to use Stirling-PDFs backend API to link with their own custom
![stirling-login](images/login-light.png) ![stirling-login](images/login-light.png)
### Prerequisites: ### Prerequisites
- User must have the folder ./configs volumed within docker so that it is retained during updates. - User must have the folder ./configs volumed within docker so that it is retained during updates.
- Docker users must download the security jar version by setting ``DOCKER_ENABLE_SECURITY`` to ``true`` in environment variables. - Docker users must download the security jar version by setting ``DOCKER_ENABLE_SECURITY`` to ``true`` in environment variables.