From 4088208fc8137c2bbc51e39a4407c1fad179584f Mon Sep 17 00:00:00 2001 From: Ludy Date: Sat, 6 Jul 2024 14:24:32 +0200 Subject: [PATCH] adding documentation for database import and export (#1528) * adding documentation for database import and export * Update DATABASE.md --- DATABASE.md | 40 +++++++++++++++++++++++++++++++ README.md | 68 +++++++++++++++++++++++++++-------------------------- 2 files changed, 75 insertions(+), 33 deletions(-) create mode 100644 DATABASE.md diff --git a/DATABASE.md b/DATABASE.md new file mode 100644 index 00000000..efc1e467 --- /dev/null +++ b/DATABASE.md @@ -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. diff --git a/README.md b/README.md index 595c1155..a60a66dc 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,7 @@ All files and PDFs exist either exclusively on the client side, reside in server - Parallel file processing and downloads - 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) +- Database Backup and Import (see [here](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DATABASE.md) for documentation) ## **PDF Features** @@ -234,35 +235,36 @@ security: csrfDisabled: true # Set to 'true' to disable CSRF protection (not recommended for production) loginAttemptCount: 5 # lock user account after 5 tries loginResetTimeMinutes: 120 # lock account for 2 hours after x attempts -# initialLogin: -# username: "admin" # Initial username for the first login -# password: "stirling" # Initial password for the first login -# oauth2: -# enabled: false # set to 'true' to enable login (Note: enableLogin must also be 'true' for this to work) -# issuer: "" # set to any provider that supports OpenID Connect Discovery (/.well-known/openid-configuration) end-point -# clientId: "" # Client ID from your provider -# clientSecret: "" # Client Secret from your provider -# autoCreateUser: false # set to 'true' to allow auto-creation of non-existing users -# useAsUsername: "email" # Default is 'email'; custom fields can be used as the username -# 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' -# client: -# google: -# clientId: "" # Client ID 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 -# useAsUsername: "email" # Field to use as the username for Google OAuth2 -# github: -# clientId: "" # Client ID for GitHub OAuth2 -# clientSecret: "" # Client Secret for GitHub OAuth2 -# scopes: "read:user" # Scope for GitHub OAuth2 -# useAsUsername: "login" # Field to use as the username for GitHub OAuth2 -# keycloak: -# issuer: "http://192.168.0.123:8888/realms/stirling-pdf" # URL of the Keycloak realm's OpenID Connect Discovery endpoint -# clientId: "stirling-pdf" # Client ID for Keycloak OAuth2 -# clientSecret: "" # Client Secret for Keycloak OAuth2 -# scopes: "openid, profile, email" # Scopes for Keycloak OAuth2 -# useAsUsername: "email" # Field to use as the username for Keycloak OAuth2 + 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) + initialLogin: + username: '' # Initial username for the first login + password: '' # Initial password for the first login + oauth2: + enabled: false # set to 'true' to enable login (Note: enableLogin must also be 'true' for this to work) + client: + keycloak: + issuer: '' # URL of the Keycloak realm's OpenID Connect Discovery endpoint + clientId: '' # Client ID for Keycloak OAuth2 + clientSecret: '' # Client Secret for Keycloak OAuth2 + scopes: openid, profile, email # Scopes for Keycloak OAuth2 + useAsUsername: preferred_username # Field to use as the username for Keycloak OAuth2 + google: + clientId: '' # Client ID 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 + useAsUsername: email # Field to use as the username for Google OAuth2 + github: + clientId: '' # Client ID for GitHub OAuth2 + clientSecret: '' # Client Secret for GitHub OAuth2 + scopes: read:user # Scope for GitHub OAuth2 + useAsUsername: login # Field to use as the username for GitHub OAuth2 + issuer: '' # set to any provider that supports OpenID Connect Discovery (/.well-known/openid-configuration) end-point + clientId: '' # Client ID from your provider + clientSecret: '' # Client Secret from your provider + autoCreateUser: false # set to 'true' to allow auto-creation of non-existing users + useAsUsername: email # Default is 'email'; custom fields can be used as the username + 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: 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 ui: - appName: null # Application's visible name - homeDescription: null # Short description or tagline shown on homepage. - appNameNavbar: null # Name displayed on the navigation bar + appName: '' # Application's visible name + homeDescription: '' # Short description or tagline shown on homepage. + appNameNavbar: '' # Name displayed on the navigation bar endpoints: 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) -### Prerequisites: +### Prerequisites - 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.